1/* 2 * Copyright 2007 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Ingo Weinhold 7 * Niels Sascha Reedijk <niels.reedijk@gmail.com> 8 * Axel Dörfler <axeld@pinc-software.de> 9 * 10 * Corresponds to: 11 * /trunk/headers/os/drivers/fs_interface.h rev 21568 12 */ 13 14/*! 15 \file fs_interface.h 16 \ingroup drivers 17 \brief Provides an interface for file system modules. 18 19 See the \ref fs_modules "introduction to file system modules" for a guide on 20 how to get started with writing file system modules. 21*/ 22 23///// write_stat_mask ////// 24 25/*! 26 \enum write_stat_mask 27 \brief This mask is used in file_system_module_info::write_stat() to 28 determine which values need to be written. 29*/ 30 31/*! 32 \var write_stat_mask::FS_WRITE_STAT_MODE 33 \brief The mode parameter should be updated. 34*/ 35 36/*! 37 \var write_stat_mask::FS_WRITE_STAT_UID 38 \brief The UID field should be updated. 39*/ 40 41/*! 42 \var write_stat_mask::FS_WRITE_STAT_GID 43 \brief The GID field should be updated. 44*/ 45 46/*! 47 \var write_stat_mask::FS_WRITE_STAT_SIZE 48 \brief The size field should be updated. If the actual size is less than the 49 new provided file size, the file should be set to the new size and the 50 extra space should be filled with zeros. 51*/ 52 53/*! 54 \var write_stat_mask::FS_WRITE_STAT_ATIME 55 \brief The access time should be updated. 56*/ 57 58/*! 59 \var write_stat_mask::FS_WRITE_STAT_MTIME 60 \brief The 'last modified' field should be updated. 61*/ 62 63/*! 64 \var write_stat_mask::FS_WRITE_STAT_CRTIME 65 \brief The 'creation time' should be updated. 66*/ 67 68///// FS_WRITE_FSINFO_NAME ///// 69 70/*! 71 \def FS_WRITE_FSINFO_NAME 72 \brief Passed to file_system_module_info::write_fs_info(). 73*/ 74 75///// file_io_vec ///// 76 77/*! 78 \struct file_io_vec 79 \brief Structure that describes the io vector of a file. 80*/ 81 82/*! 83 \var off_t file_io_vec::offset 84 \brief The offset within the file. 85*/ 86 87/*! 88 \var off_t file_io_vec::length 89 \brief The length of the vector. 90*/ 91 92///// B_CURRENT_FS_API_VERSION ///// 93 94/*! 95 \def B_CURRENT_FS_API_VERSION 96 \brief Constant that defines the version of the file system API that your 97 filesystem conforms to. 98 99 The module name that exports the interface to your file system has to 100 end with this constant as in: 101 \code "file_systems/myfs" B_CURRENT_FS_API_VERSION \endcode 102*/ 103 104///// file_system_module_info ///// 105 106 107/*! 108 \struct file_system_module_info 109 \brief Kernel module interface for file systems. 110 111 See the \ref fs_modules "introduction to file system modules" for an 112 introduction to writing file systems. 113*/ 114 115/*! 116 \name Data members 117*/ 118 119//! @{ 120 121/*! 122 \var module_info file_system_module_info::info 123 \brief Your module_info object which is required for all modules. 124*/ 125 126/*! 127 \var const char *file_system_module_info::pretty_name 128 \brief A NULL-terminated string with a 'pretty' name for you file system. 129 130 Note, if a system wide disk device type constant exists for your file system, 131 it should equal this identifier. 132*/ 133 134//! @} 135 136/*! 137 \name Scanning 138*/ 139 140//! @{ 141 142/*! 143 \fn float (*file_system_module_info::identify_partition)(int fd, 144 partition_data *partition, void **cookie) 145 \brief Undocumented. TODO. 146*/ 147 148/*! 149 \fn status_t (*file_system_module_info::scan_partition)(int fd, 150 partition_data *partition, void *cookie) 151 \brief Undocumented. TODO. 152*/ 153 154/*! 155 \fn void (*file_system_module_info::free_identify_partition_cookie)( 156 partition_data *partition, void *cookie) 157 \brief Undocumented. TODO. 158*/ 159 160/*! 161 \fn void (*file_system_module_info::free_partition_content_cookie)( 162 partition_data *partition) 163 \brief Undocumented. TODO. 164*/ 165 166//! @} 167 168/*! 169 \name General Operations 170*/ 171 172//! @{ 173 174/*! 175 \fn status_t (*file_system_module_info::mount)(ino_t id, const char *device, 176 uint32 flags, const char *args, fs_volume *_fs, ino_t *_rootVnodeID) 177 \brief Mount a volume according to the specified parameters. 178 179 Invoked by the VFS when it has been requested to mount the volume. The FS is 180 supposed to perform whatever one-time initialization is necessary for the 181 volume. It is required to create a volume handle for the volume and pass it 182 back in \a _fs. Moreover it must invoke publish_vnode() for the root node 183 of the volume and pass the ID of the volume back in \a _rootVnodeID. 184 185 A disk-based FS will need to check whether \a device is not \c NULL, open 186 it, and analyze whether the device or image file actually represents a volume 187 of that FS type. 188 189 If mounting the volume fails for whatever reason, the hook must return an 190 error code other than \c B_OK. In this case all resources allocated by the 191 hook must be freed before returning. If and only if \c B_OK is returned, the 192 unmount() hook will be invoked at a later point when unmounting the volume. 193 194 \param id The ID of the volume to be mounted. It should be saved in the FS's 195 volume private data (volume handle). 196 \param device The path to the device (or image file) representing the volume 197 to be mounted. Can be \c NULL. 198 \param flags Flags: 199 - \c B_MOUNT_READ_ONLY: Mount the volume read-only. 200 \param args Null-terminated string in driver settings format, containing FS 201 specific parameters. 202 \param _fs Pointer to a pre-allocated variable the volume handle shall be 203 written to. 204 \param _rootVnodeID Pointer to a pre-allocated variable the ID of the 205 volume's root directory shall be written to. 206 \return \c B_OK if everything went fine, another error code otherwise. 207*/ 208 209/*! 210 \fn status_t (*file_system_module_info::unmount)(fs_volume fs) 211 \brief Unmounts the given volume. 212 213 Invoked by the VFS when it is asked to unmount the volume. The function must 214 free all resources associated with the mounted volume, including the volume 215 handle. Although the mount() hook called publish_vnode() for the root node 216 of the volume, unmount() must not invoke put_vnode(). 217 218 \param fs The volume handle. 219 \return \c B_OK if everything went fine, another error code otherwise. The 220 error code will be ignored, though. 221*/ 222 223/*! 224 \fn status_t (*file_system_module_info::read_fs_info)(fs_volume fs, 225 struct fs_info *info) 226 \brief Retrieves general information about the volume. 227 228 The following fields of the \c fs_info structure need to be filled in: 229 - \c flags: Flags applying to the volume, e.g. \c B_FS_IS_READONLY, 230 \c B_FS_HAS_ATTR, etc. 231 - \c block_size: The size of blocks the volume data are organized in. 232 Meaningful mainly for disk-based FSs, other FSs should use some reasonable 233 value for computing \c total_blocks and \c free_blocks. 234 - \c io_size: Preferred size of the buffers passed to read() and write(). 235 - \c total_blocks: Total number of blocks the volume contains. 236 - \c free_blocks: Number of free blocks on the volume. 237 - \c total_nodes: Maximal number of nodes the volume can contain. If there is 238 no such limitation use \c LONGLONG_MAX. 239 - \c free_nodes: Number of additional nodes the volume could contain. If 240 there is no such limitation use \c LONGLONG_MAX. 241 - \c device_name: The name of the device or image file containing the volume. 242 Non-disk-based FSs shall fill in an empty string. 243 - \c volume_name: The name of the volume. 244 245 The other values are filled in by the VFS. 246 247 \param fs The volume handle. 248 \param info Pointer to a pre-allocated variable the FS info shall be written 249 to. 250 \return \c B_OK if everything went fine, another error code otherwise. The 251 error code will be ignored, though. 252*/ 253 254/*! 255 \fn status_t (*file_system_module_info::write_fs_info)(fs_volume fs, 256 const struct fs_info *info, uint32 mask) 257 \brief Update filesystem information on the volume. 258 259 You are requested to update certain information on the volume \a fs. The 260 supplied \a info contains the new values filled in for the \a mask. 261 Currently, the only possible mask is solely the \c FS_WRITE_FSINFO_NAME, 262 which asks you to update the volume name represented by the value 263 \c volume_name in the \c fs_info struct. 264 265 \param fs The cookie your filesystem supplied to the volume that should be 266 updated. 267 \param info The structure that contains the new data. 268 \param mask The values of the \a info that need to be updated. 269 \return \c B_OK if everything went fine, if not, one of the error codes. 270*/ 271 272/*! 273 \fn status_t (*file_system_module_info::sync)(fs_volume fs) 274 \brief Synchronize the cached data with the contents of the disk. 275 276 The VFS layer sometimes wants you to synchronize any cached values with the 277 data on the device. 278 279 This currently only happens when the POSIX sync() function is invoked, for 280 example via the "sync" command line tool. 281 282 \param fs The cookie your filesystem supplied to the volume that should be 283 updated. 284*/ 285 286//! @} 287 288/*! 289 \name VNode Operations 290*/ 291 292//! @{ 293 294/*! 295 \fn status_t (*file_system_module_info::lookup)(fs_volume fs, fs_vnode dir, 296 const char *name, ino_t *_id, int *_type) 297 \brief Looks up the node a directory entry refers to. 298 299 The VFS uses this hook to resolve path names to vnodes. It is used quite 300 often and should be implemented efficiently. 301 302 If the parameter \a dir does not specify a directory, the function shall 303 fail. It shall also fail, if it is a directory, but does not contain an entry 304 with the given name \a name. Otherwise the function shall invoke get_vnode() 305 for the node the entry refers to and pass back the ID and the type of the 306 node in \a _id and \a _type respectively. 307 308 Note that a directory must contain the special entries \c "." and \c "..", 309 referring to the same directory and the parent directory respectively. 310 lookup() must resolve the nodes accordingly. \c ".." for the root directory 311 of the volume shall be resolved to the root directory itself. 312 313 \param fs The volume handle. 314 \param dir The node handle of the directory. 315 \param name The name of the directory entry. 316 \param _id Pointer to a pre-allocated variable the ID of the found node 317 shall be written to. 318 \param _type Pointer to a pre-allocated variable the type of the found node 319 shall be written to. The type is encoded as in the \c st_mode field of a 320 <tt>struct stat</tt> (bitwise anded with \c S_IFMT). 321 \retval B_OK Everything went fine. 322 \retval B_ENTRY_NOT_FOUND The given directory does not contain an entry with 323 the given name. 324*/ 325 326/*! 327 \fn status_t (*file_system_module_info::get_vnode_name)(fs_volume fs, 328 fs_vnode vnode, char *buffer, size_t bufferSize) 329 \brief Return the file name of a vnode. 330 331 Note that you don't have to implement this call if it can't be easily done; 332 it's completely optional. 333 If you don't implement it, you'll have to export a NULL pointer for this 334 function in the module definition. In this case, the VFS will find the name 335 by iterating over its parent directory. 336 337 \param fs The file system provided cookie associated with this volume. 338 \param vnode The file system provided cookie associated with this vnode. 339 \param buffer The buffer that the name can be copied into. 340 \param bufferSize The size of the buffer. 341 \retval B_OK You successfully copied the file name into the \a buffer. 342 \retval "other errors" There was some error looking up or copying the name. 343*/ 344 345/*! 346 \fn status_t (*file_system_module_info::get_vnode)(fs_volume fs, ino_t id, 347 fs_vnode *_vnode, bool reenter) 348 \brief Creates the private data handle to be associated with the node 349 referred to by \a id. 350 351 Invoked by the VFS when it creates the vnode for the respective node. 352 When the VFS no longer needs the vnode in memory (for example when 353 memory is becoming tight), it will your file_system_module_info::put_vnode(), 354 or file_system_module_info::remove_vnode() in case the vnode has been 355 marked removed. 356 357 \param fs The volume handle. 358 \param id The ID of the node. 359 \param _vnode Pointer to a pre-allocated variable the node handle shall be 360 written to. 361 \param reenter \c true if the hook invocation has been caused by the FS 362 itself, e.g. by invoking ::get_vnode(). 363 \return \c B_OK if everything went fine, another error code otherwise. 364*/ 365 366/*! 367 \fn \fn status_t (*file_system_module_info::put_vnode)(fs_volume fs, 368 fs_vnode vnode, bool reenter) 369 \brief Deletes the private data handle associated with the specified node. 370 371 Invoked by the VFS when it deletes the vnode for the respective node and the 372 node is not marked removed. 373 374 \param fs The volume handle. 375 \param vnode The node handle. 376 \param reenter \c true if the hook invocation has been caused by the FS 377 itself, e.g. by invoking ::put_vnode(). 378 \return \c B_OK if everything went fine, another error code otherwise. 379*/ 380 381/*! 382 \fn status_t (*file_system_module_info::remove_vnode)(fs_volume fs, 383 fs_vnode vnode, bool reenter) 384 \brief Deletes the private data handle associated with the specified node. 385 386 Invoked by the VFS when it deletes the vnode for the respective node and the 387 node has been marked removed by a call to remove_vnode(). 388 389 \param fs The volume handle. 390 \param vnode The node handle. 391 \param reenter \c true if the hook invocation has been caused by the FS 392 itself, e.g. by invoking ::put_vnode(). 393 \return \c B_OK if everything went fine, another error code otherwise. 394*/ 395 396//! @} 397 398/*! 399 \name VM file access 400*/ 401 402//! @{ 403 404/*! 405 \fn bool (*file_system_module_info::can_page)(fs_volume fs, fs_vnode vnode, 406 fs_cookie cookie) 407 \brief Undocumented. TODO. 408 409 TODO: In both the dos and the bfs implementations this thing simply returns 410 false... Is there anything more to it? 411 This call might be removed in the future - it's currently unused. 412*/ 413 414/*! 415 \fn status_t (*file_system_module_info::read_pages)(fs_volume fs, fs_vnode vnode, 416 fs_cookie cookie, off_t pos, const iovec *vecs, size_t count, 417 size_t *_numBytes, bool reenter) 418 \brief Undocumented. TODO. 419*/ 420 421/*! 422 \fn status_t (*file_system_module_info::write_pages)(fs_volume fs, fs_vnode vnode, 423 fs_cookie cookie, off_t pos, const iovec *vecs, size_t count, 424 size_t *_numBytes, bool reenter) 425 \brief Undocumented. TODO. 426*/ 427 428//! @} 429 430/*! 431 \name Cache File Access 432*/ 433 434//! @{ 435 436/*! 437 \fn status_t (*file_system_module_info::get_file_map)(fs_volume fs, 438 fs_vnode vnode, off_t offset, size_t size, struct file_io_vec *vecs, 439 size_t *_count) 440 \brief Fills the \a vecs with the extents of the file data stream. 441 442 This function is called only when you are using the file cache, but if you 443 use it, its implementation is mandatory. 444 445 TODO: complete me 446*/ 447 448//! @} 449 450/*! 451 \name Standard Operations 452*/ 453 454//! @{ 455 456/*! 457 \fn status_t (*file_system_module_info::ioctl)(fs_volume fs, fs_vnode vnode, 458 fs_cookie cookie, ulong op, void *buffer, size_t length) 459 \brief Perform file system specific operations. 460 461 You can implement a customized API using this call. This can be extremely 462 handy for debugging purposes. There are no obligatory operations for you to 463 implement. 464 465 If you don't want to use this feature, you don't have to implement it. 466 467 \param fs The file system provided cookie associated with this volume. 468 \param vnode The file system provided cookie associated with the vnode (if 469 applicable). 470 \param cookie The file system provided cookie associated with, for example, 471 an open file (if applicable). 472 \param op The operation code. You will have to define them yourself. 473 \param buffer A buffer (if applicable). 474 \param length The size of the buffer. 475 \return You should return any of your status codes. 476*/ 477 478/*! 479 \fn status_t (*file_system_module_info::set_flags)(fs_volume fs, 480 fs_vnode vnode, fs_cookie cookie, int flags) 481 \brief Set the open mode flags for an opened file. 482 483 This function should change the open flags for an opened file. 484 485 \param fs The file system provided cookie associated with this volume. 486 \param vnode The file system provided cookie associated with the vnode. 487 \param cookie The file system provided cookie associated with the opened 488 file. 489 \param flags The new flags. 490 \return \c B_OK if the operation succeeded, or else an error code. 491*/ 492 493/*! 494 \fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode, 495 fs_cookie cookie, uint8 event, uint32 ref, selectsync *sync) 496 \brief Selects the specified \a vnode with the specified \a events. 497 498 This function is called by the VFS whenever select() or poll() is called on 499 a file descriptor that points to your file system. 500 501 You have to check if the condition of the select() (ie. if there is data 502 available if event is B_SELECT_READ) is already satisfied, and call 503 notify_select_event() with the \a sync and \a ref arguments you retrieve 504 here. 505 506 Additionally, when a vnode is selected this way, you have to call 507 notify_select_event() whenever the condition becomes true until the 508 vnode is deselected again via file_system_module_info::deselect(). 509 510 This function is optional. If you don't export it, the default implementation 511 in the VFS will call notify_select_event() directly which will be sufficient 512 for most file systems. 513*/ 514 515/*! 516 \fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode, 517 fs_cookie cookie, uint8 event, selectsync *sync) 518 \brief Deselects the specified \a vnode from a previous select() call. 519 520 This function is called by the VFS whenever a select() or poll() function 521 exits that previously called file_system_module_info::select() on that 522 \a vnode. 523*/ 524 525/*! 526 \fn status_t (*file_system_module_info::fsync)(fs_volume fs, fs_vnode vnode) 527 \brief Synchronize the buffers with the on disk data. 528 529 \param fs The file system provided cookie associated with this volume. 530 \param vnode The file system provided cookie associated with the vnode. 531 \return \c B_OK if the operation succeeded, or else an error code. 532*/ 533 534/*! 535 \fn status_t (*file_system_module_info::read_symlink)(fs_volume fs, 536 fs_vnode link, char *buffer, size_t *_bufferSize) 537 \brief Read the value of a symbolic link. 538 539 If the function is successful, the string written to the buffer shall be 540 null-terminated and the variable \a _bufferSize points to shall be set to 541 the length of that string, including the terminating null character. 542 543 \param fs The volume handle. 544 \param link The node handle. 545 \param buffer Pointer to a pre-allocated buffer the link value shall be 546 written to. 547 \param buffer Pointer to a pre-allocated variable containing the size of the 548 buffer supplied to the function. Upon successful completion the hook shall 549 store the number of bytes actually written into the buffer in the variable. 550 \retval B_OK Everything went fine. 551 \retval B_BAD_VALUE \a link does not identify a symbolic link. 552 \retval B_BUFFER_OVERFLOW The supplied buffer is not big enough to contain 553 the complete link value. 554*/ 555 556/*! 557 \fn status_t (*file_system_module_info::create_symlink)(fs_volume fs, 558 fs_vnode dir, const char *name, const char *path, int mode) 559 \brief Create a new symbolic link. 560 561 Your implementation should check if the user has permission to perform this 562 operation. 563 564 \param fs The file system provided cookie associated with this volume. 565 \param dir The file system provided cookie associated with the directory 566 the symbolic link should be created in. 567 \param name The name of the new symbolic link. 568 \param path The path of the original inode the symbolic link should refer to. 569 \param mode The mode that this symbolic link should be created in. (TODO 570 what exactly?) 571 \return \c B_OK if you succeeded, or an error code if you failed. 572*/ 573 574/*! 575 \fn status_t (*file_system_module_info::link)(fs_volume fs, fs_vnode dir, 576 const char *name, fs_vnode vnode) 577 \brief Create a new hard link. 578 579 You should make sure the user has the proper permissions. 580 581 The virtual file system will request the creation of symbolic links with 582 create_symlink(). 583 584 If you don't implement this function, the VFS will return \c EROFS 585 when a hard link is requested. 586 587 \param fs The file system provided cookie associated with this volume. 588 \param dir The cookie associated to the directory where the link should be 589 saved. 590 \param name The name the link should have. 591 \param vnode The vnode the new link should resolve to. 592 \retval B_OK The hard link is properly created. 593 \retval B_NOT_ALLOWED The user does not have the proper permissions. 594 \retval "other errors" Another error occured. 595*/ 596 597/*! 598 \fn status_t (*file_system_module_info::unlink)(fs_volume fs, fs_vnode dir, 599 const char *name) 600 \brief Remove a node or directory. 601 602 You should make sure the user has the proper permissions. 603 604 \param fs The file system provided cookie associated with this volume. 605 \param dir The parent directory of the node that should be removed. 606 \param name The name of the node that should be deleted. 607 \retval B_OK Removal succeeded. 608 \retval B_ENTRY_NOT_FOUND The entry does not exist. 609 \retval B_NOT_ALLOWED The user does not have the proper permissions. 610 \retval B_DIRECTORY_NOT_EMPTY The \a name refers to a directory. The virtual 611 file system expects directories to be emptied before they can be unlinked. 612 \retval "other errors" Another error occured. 613*/ 614 615/*! 616 \fn status_t (*file_system_module_info::rename)(fs_volume fs, 617 fs_vnode fromDir, const char *fromName, fs_vnode toDir, 618 const char *toName) 619 \brief Rename and/or relocate a vnode. 620 621 The virtual file system merely relays the request, so make sure the user is 622 not changing the file name to something like '.', '..' or anything starting 623 with '/'. 624 625 This also means that it if the node is a directory, that it should not be 626 moved into one of its own children. 627 628 You should also make sure the user has the proper permissions. 629 630 \param fs The file system provided cookie associated with this volume. 631 \param fromDir The cookie of the parent directory the vnode should be moved 632 from. 633 \param fromName The old name of the node. 634 \param toDir The cookie of the parent directory the vnode should be moved to. 635 \param toName The new name of the node. 636 \retval B_OK The renaming and relocating succeeded. 637 \retval B_BAD_VALUE One of the supplied parameters were invalid. 638 \retval B_NOT_ALLOWED The user does not have the proper permissions. 639 \retval "other errors" Another error condition was encountered. 640*/ 641 642/*! 643 \fn status_t (*file_system_module_info::access)(fs_volume fs, fs_vnode vnode, 644 int mode) 645 \brief Checks whether the current user is allowed to access the node in the 646 specified way. 647 648 \a mode is a bitwise combination of: 649 - \c R_OK: Read access. 650 - \c W_OK: Write access. 651 - \c X_OK: Execution. 652 653 If the current user does not have any of the access permissions represented 654 by the set bits, the function shall return \c B_NOT_ALLOWED. As a special 655 case, if the volume is read-only and write access is requested, 656 \c B_READ_ONLY_DEVICE shall be returned. If the requested access mode 657 complies with the user's access permissions, the function shall return 658 \c B_OK. 659 660 For most FSs the permissions a user has are defined by the \c st_mode, 661 \c st_uid, and \c st_gid fields of the node's stat data. As a special 662 exception, the root user (<tt>geteuid() == 0</tt>) does always have 663 read and write permissions, execution permission only when at least one of 664 the execution permission bits are set. 665 666 \param fs The volume handle. 667 \param vnode The node handle. 668 \param mode The access mode mask. 669 \retval B_OK The user has the permissions to access the node in the requested 670 way. 671 \retval B_READ_ONLY_DEVICE The volume is read-only, but the write access has 672 been requested. 673 \retval B_NOT_ALLOWED The user does not have all permissions to access the 674 node in the requested way. 675*/ 676 677/*! 678 \fn status_t (*file_system_module_info::read_stat)(fs_volume fs, 679 fs_vnode vnode, struct stat *stat) 680 \brief Retrieves the stat data for a given node. 681 682 All values of the <tt>struct stat</tt> save \c st_dev, \c st_ino, \c st_rdev, 683 and \c st_type need to be filled in. 684 685 \param fs The volume handle. 686 \param vnode The node handle. 687 \param stat Pointer to a pre-allocated variable the stat data shall be 688 written to. 689 \return \c B_OK if everything went fine, another error code otherwise. 690*/ 691 692/*! 693 \fn status_t (*file_system_module_info::write_stat)(fs_volume fs, 694 fs_vnode vnode, const struct stat *stat, uint32 statMask) 695 \brief Update the stats for a vnode. 696 697 You should make sure that the new values are valid and that the user has the 698 proper permissions to update the stats. 699 700 \param fs The file system provided cookie to the volume. 701 \param vnode The cookie to the vnode. 702 \param stat The structure with the updated values. 703 \param statMask One of the #write_stat_mask enumeration, which forms a mask 704 of which of the values in \a stat should actually be updated. 705 \retval B_OK The update succeeded. 706 \retval B_NOT_ALLOWED The user does not have the proper permissions. 707 \retval "other errors" Another error condition occured. 708*/ 709 710//! @} 711 712/*! 713 \name File Operations 714*/ 715 716//! @{ 717 718/*! 719 \fn status_t (*file_system_module_info::create)(fs_volume fs, fs_vnode dir, 720 const char *name, int openMode, int perms, fs_cookie *_cookie, 721 ino_t *_newVnodeID) 722 \brief Create a new file. 723 724 Your implementation shall check whether it is possible to create the node. 725 You will need to take the user's permissions into account. When you create 726 a new file, you will also have to open it. This means also checking the 727 permissions the user requires to open the file according to the \a mode. 728 See \link file_system_module_info::open() open() \endlink for the possible 729 values of \a mode. 730 731 \param fs The file system provided cookie associated with this volume. 732 \param dir The file system provided cookie associated with the directory 733 where the file should appear. 734 \param name The name of the new file. 735 \param openMode The mode associated to the file. 736 \param perms The permissions the new file should have. 737 \param[out] _cookie In case of success, the you can store your file system 738 data for this node in this variable. 739 \param[out] _newVnodeID In case of success, you can store the new vnode id 740 in this variable. 741 \return You should return \c B_OK if creating the new node succeeded, and if 742 you put data in both \a _cookie and \a _newVnodeID. Else you should return 743 an error code. 744*/ 745 746/*! 747 \fn status_t (*file_system_module_info::open)(fs_volume fs, fs_vnode vnode, 748 int openMode, fs_cookie *_cookie) 749 \brief Opens the given node. 750 751 The function shall check whether it is possible to open the node according to 752 the mode specified by \c openMode (also considering the user's access 753 permissions), create a node cookie, and store it in the variable 754 \a _cookie points to. 755 756 The open mode \a openMode is encoded in the same way as the parameter of the 757 POSIX function \c open(), i.e. it is either \c O_RDONLY, \c O_WRONLY, or 758 \c O_RDWR, bitwise or'ed with flags. The only relevant flags for this hook 759 are \c O_TRUNC and \c O_NONBLOCK. 760 761 \param fs The volume handle. 762 \param vnode The node handle. 763 \param openMode The open mode. 764 \param _cookie Pointer to a pre-allocated variable the node cookie shall be 765 written to. 766 \return \c B_OK if everything went fine, another error code otherwise. 767*/ 768 769/*! 770 \fn status_t (*file_system_module_info::close)(fs_volume fs, fs_vnode vnode, 771 fs_cookie cookie) 772 \brief Closes the given node cookie. 773 774 The hook is invoked, when closing the node has been requested. At this point 775 other threads might still use the cookie, i.e. still execute hooks to which 776 the cookie has been passed. If the FS supports blocking I/O operations, this 777 hook should make sure to unblock all currently blocking threads performing 778 an operation using the cookie, and mark the cookie such that no further 779 threads will block using it. 780 781 For many FSs this hook is a no-op - it's mandatory to be exported, though. 782 783 \param fs The volume handle. 784 \param vnode The node handle. 785 \param cookie The node cookie as returned by open(). 786 \return \c B_OK if everything went fine, another error code otherwise. 787*/ 788 789/*! 790 \fn status_t (*file_system_module_info::free_cookie)(fs_volume fs, 791 fs_vnode vnode, fs_cookie cookie) 792 \brief Frees the given node cookie. 793 794 The hook is invoked after close(), when no other thread uses or is going to 795 use the cookie. All resources associated with the cookie must be freed. 796 797 \param fs The volume handle. 798 \param vnode The node handle. 799 \param cookie The node cookie as returned by open(). 800 \return \c B_OK if everything went fine, another error code otherwise. 801*/ 802 803/*! 804 \fn status_t (*file_system_module_info::read)(fs_volume fs, fs_vnode vnode, 805 fs_cookie cookie, off_t pos, void *buffer, size_t *length) 806 \brief Reads data from a file. 807 808 This function should fail if 809 - the node is not a file, 810 - the cookie has not been opened for reading, 811 - \a pos is negative, or 812 - some other error occurs while trying to read the data, and no data have 813 been read at all. 814 815 The number of bytes to be read is stored in the variable pointed to by 816 \a length. If less data is available at file position \a pos, or if \a pos 817 if greater than the size of the file, only as many data as available shall 818 be read, the function shall store the number of bytes actually read into the 819 variable pointed to by \a length, and return \c B_OK. 820 821 \param fs The volume handle. 822 \param vnode The node handle. 823 \param cookie The node cookie as returned by open(). 824 \param pos The file position where to start reading data. 825 \param buffer Pointer to a pre-allocated buffer the read data shall be 826 written to. 827 \param length Pointer to a pre-allocated variable containing the size of the 828 buffer when invoked, and into which the size of the data actually read 829 shall be written. 830 \return \c B_OK if everything went fine, another error code otherwise. 831*/ 832 833/*! 834 \fn status_t (*file_system_module_info::write)(fs_volume fs, fs_vnode vnode, 835 fs_cookie cookie, off_t pos, const void *buffer, size_t *length) 836 \brief Write data to a file. 837 838 This function should fail if 839 - the node is not a file, 840 - the cookie has not been opened for writing, 841 - \a pos is negative, or 842 - some other error occurs while trying to read the data, and no data have 843 been read at all. 844 845 The number of bytes to be written is stored in the variable pointed to by 846 \a length. If not all bytes could be written, that variable must be updated 847 to reflect the amount of actually written bytes. If an error prevented 848 you from writing the full amount, an appropriate error code should be 849 returned. 850 851 \param fs The file system provided cookie associated with this volume. 852 \param vnode The file system provided cookie associated with the vnode. 853 \param cookie The file system provided cookie associated with the file. 854 \param pos The position to start writing. 855 \param buffer The buffer that contains the data that will need to be written. 856 \param length The length of the data that needs to be written. 857 \return \c B_OK if everything went fine, another error code otherwise. 858*/ 859 860//! @} 861 862/*! 863 \name Directory Operations 864*/ 865 866/*! 867 \fn status_t (*file_system_module_info::create_dir)(fs_volume fs, fs_vnode 868 parent, const char *name, int perms, ino_t *_newVnodeID) 869 \brief Create a new directory. 870 871 Your implementation should make sure that the directory actually can be 872 created in the \a parent directory. You will have to check if the user has 873 permissions to actually write to the \a parent. If not, this function should 874 fail (probably with \c B_NOT_ALLOWED, or in case of a read-only filesystem, 875 with \c B_READ_ONLY_DEVICE). If the operation succeeds, you should put the 876 new vnode id in \a _newVnodeID. 877 878 \param fs The file system provided cookie associated with this volume. 879 \param parent The file system provided cookie associated with the parent 880 node. 881 \param name The name the new directory should have. 882 \param perms The permissions the new directory should have. 883 \param[out] _newVnodeID If creating the directory succeeds, than you should 884 put the new vnode id in this variable. 885 \return If the operation succeeds and the \a _newVnodeID is populated with 886 the new vnode, then you should return \c B_OK. Else you should return with 887 an error code. 888*/ 889 890/*! 891 \fn status_t (*file_system_module_info::remove_dir)(fs_volume fs, fs_vnode 892 parent, const char *name) 893 \brief Remove a directory. 894 895 You should make sure the user has the proper permissions. You should also 896 check that the directory is empty. 897 898 \param fs The file system provided cookie associated with this volume. 899 \param parent The file system provided cookie associated with the parent 900 node. 901 \param name The \a name of the directory that needs to be removed. 902 \retval B_OK Operation succeeded. 903 \retval B_DIRECTORY_NOT_EMPTY The directory is not empty. 904 \retval B_ENTRY_NOT_FOUND There is no directory with this \a name. 905 \retval B_NOT_A_DIRECTORY The entry is not a directory. 906 \retval "other errors" Other errors occured. 907*/ 908 909/*! 910 \fn status_t (*file_system_module_info::open_dir)(fs_volume fs, fs_vnode vnode, 911 fs_cookie *_cookie) 912 \brief Opens the given directory node. 913 914 If the specified node is not a directory, or if the current user does not 915 have the permissions to read the directory, the function shall fail. 916 Otherwise it shall allocate a directory cookie and store it in the variable 917 \a _cookie points to. A subsequent read_dir() using the cookie shall start 918 reading the first entry of the directory. 919 920 \param fs The volume handle. 921 \param vnode The node handle. 922 \param _cookie Pointer to a pre-allocated variable the directory cookie shall 923 be written to. 924 \return \c B_OK if everything went fine, another error code otherwise. 925*/ 926 927/*! 928 \fn status_t (*file_system_module_info::close_dir)(fs_volume fs, 929 fs_vnode vnode, fs_cookie cookie) 930 \brief Closes the given directory cookie. 931 932 Generally the situation is similar to the one described for close(). In 933 practice it is a bit, though, since directory cookies are exclusively used 934 for directory iteration, and it normally doesn't make sense to have multiple 935 threads read the same directory concurrently. Furthermore reading a directory 936 should not block. Therefore for most FSs this hook is a no-op. 937 938 \param fs The volume handle. 939 \param vnode The node handle. 940 \param cookie The directory cookie as returned by open_dir(). 941 \return \c B_OK if everything went fine, another error code otherwise. 942*/ 943 944/*! 945 \fn status_t (*file_system_module_info::free_dir_cookie)(fs_volume fs, 946 fs_vnode vnode, fs_cookie cookie) 947 \brief Frees the given directory cookie. 948 949 The hook is invoked after close_dir(), when no other thread uses or is going 950 to use the cookie. All resources associated with the cookie must be freed. 951 952 \param fs The volume handle. 953 \param vnode The node handle. 954 \param cookie The directory cookie as returned by open_dir(). 955 \return \c B_OK if everything went fine, another error code otherwise. 956*/ 957 958/*! 959 \fn status_t (*file_system_module_info::read_dir)(fs_volume fs, fs_vnode vnode, 960 fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num) 961 \brief Reads the next one or more directory entries. 962 963 The number of entries to be read at maximum is stored in the variable \a _num 964 points to. 965 966 Per read \c dirent the following fields have to be filled in: 967 - \c d_dev: The volume ID. 968 - \c d_ino: The ID of the node the entry refers to. 969 - \c d_name: The null-terminated name of the entry. 970 - \c d_reclen: The size of the \c dirent structure in bytes, starting from 971 the beginning of the structure, counting all bytes up to and including 972 the null-termination char of the name stored in \c d_name. 973 974 If more than one entry is read, the corresponding \c dirent structures are 975 tightly packed, i.e. the second entry begins directly after the end of the 976 first one (i.e. \c d_reclen bytes after the beginning of the first one). 977 Most FSs read only one entry at a time though, even if more are requested. 978 979 When the function is invoked after the end of the directory has been reached, 980 it shall set the variable \a _num points to to \c 0 and return \c B_OK. If 981 the provided buffer is too small to contain even the single next entry, 982 \c B_BUFFER_OVERFLOW shall be returned. It shall not fail, if at least one 983 entry has been read, and the buffer is just too small to hold as many entries 984 as requested. 985 986 Note that a directory is expected to contain the special entries \c "." and 987 \c "..", referring to the same directory and the parent directory 988 respectively. The \c dirent structure returned for the \c ".." entry of the 989 volume's root directory shall refer to the root node itself. 990 991 \param fs The volume handle. 992 \param vnode The node handle. 993 \param cookie The directory cookie as returned by open_dir(). 994 \param buffer Pointer to a pre-allocated buffer the directory entries shall 995 be written to. 996 \param bufferSize The size of \a buffer in bytes. 997 \param _num Pointer to a pre-allocated variable, when invoked, containing the 998 number of directory entries to be read, and into which the number of 999 entries actually read shall be written. 1000 \return \c B_OK if everything went fine, another error code otherwise. 1001*/ 1002 1003/*! 1004 \fn status_t (*file_system_module_info::rewind_dir)(fs_volume fs, 1005 fs_vnode vnode, fs_cookie cookie) 1006 \brief Resets the directory cookie to the first entry of the directory. 1007 \param fs The volume handle. 1008 \param vnode The node handle. 1009 \param cookie The directory cookie as returned by open_dir(). 1010 \return \c B_OK if everything went fine, another error code otherwise. 1011*/ 1012 1013//! @} 1014 1015/*! 1016 \name Attribute Directory Operations 1017*/ 1018 1019//! @{ 1020 1021/*! 1022 \fn status_t (*file_system_module_info::open_attr_dir)(fs_volume fs, fs_vnode 1023 vnode, fs_cookie *_cookie) 1024 \brief Open a 'directory' of attributes for a \a vnode. 1025 1026 See \ref concepts "Generic Concepts" on directories and iterators. Basically, 1027 the VFS uses the same way of traversing through attributes as it traverses 1028 through a directory. 1029 1030 \param fs The file system provided cookie to the volume. 1031 \param vnode The vnode on which the file system wants to read the attributes. 1032 \param[out] _cookie Pointer where the file system can store a directory 1033 cookie if the attribute directory is succesfully opened. 1034 \return \c B_OK if everything went fine, another error code otherwise. 1035*/ 1036 1037/*! 1038 \fn status_t (*file_system_module_info::close_attr_dir)(fs_volume fs, 1039 fs_vnode vnode, fs_cookie cookie) 1040 \brief Close a 'directory' of attributes for a \a vnode. 1041 1042 Note that you should free the cookie in the free_attr_dir_cookie() call. 1043 1044 \param fs The file system provided cookie to the volume. 1045 \param vnode The vnode on which the 'directory' was opened. 1046 \param cookie The cookie associated with this 'directory'. 1047 \return \c B_OK if everything went fine, another error code otherwise. 1048*/ 1049 1050/*! 1051 \fn status_t (*file_system_module_info::free_attr_dir_cookie)(fs_volume fs, 1052 fs_vnode vnode, fs_cookie cookie) 1053 \brief Free the \a cookie to an attribute 'directory'. 1054 1055 \param fs The file system provided cookie to the volume. 1056 \param vnode The vnode on which the 'directory' was opened. 1057 \param cookie The cookie associated that should be freed. 1058 \return \c B_OK if everything went fine, another error code otherwise. 1059*/ 1060 1061/*! 1062 \fn status_t (*file_system_module_info::read_attr_dir)(fs_volume fs, fs_vnode 1063 vnode, fs_cookie cookie, struct dirent *buffer, size_t bufferSize, 1064 uint32 *_num) 1065 \brief Read the next one or more attribute directory entries. 1066 1067 This method should perform the same tasks as read_dir(), except that the '.' 1068 and '..' entries do not have to be present. 1069*/ 1070 1071/*! 1072 \fn status_t (*file_system_module_info::rewind_attr_dir)(fs_volume fs, 1073 fs_vnode vnode, fs_cookie cookie) 1074 \brief Rewind the attribute directory iterator to the first entry. 1075 1076 \param fs The file system provided cookie to the volume. 1077 \param vnode The vnode on which the 'directory' was opened. 1078 \param cookie The cookie associated with this 'directory'. 1079 \return \c B_OK if everything went fine, another error code otherwise. 1080*/ 1081 1082//! @} 1083 1084/*! 1085 \name Attribute Operations 1086*/ 1087 1088//! @{ 1089 1090/*! 1091 \fn status_t (*file_system_module_info::create_attr)(fs_volume fs, fs_vnode 1092 vnode, const char *name, uint32 type, int openMode, fs_cookie *_cookie) 1093 \brief Create a new attribute. 1094 1095 If the attribute already exists, you should open it in truncated mode. 1096 1097 \param fs The file system provided cookie to the volume. 1098 \param vnode The file system provided cookie to the vnode. 1099 \param name The name of the attribute. 1100 \param type The \c type_code of the attribute. 1101 \param openMode The openMode of the associated attribute. 1102 \param[out] _cookie A pointer where you can store an associated file system 1103 cookie. 1104 \return \c B_OK if everything went fine, another error code otherwise. 1105*/ 1106 1107/*! 1108 \fn status_t (*file_system_module_info::open_attr)(fs_volume fs, fs_vnode 1109 vnode, const char *name, int openMode, fs_cookie *_cookie) 1110 \brief Open an existing attribute. 1111 1112 \param fs The file system provided cookie to the volume. 1113 \param vnode The file system provided cookie to the vnode. 1114 \param name The name of the attribute. 1115 \param openMode The mode in which you want to open the attribute data. 1116 \param[out] _cookie A pointer where you can store an associated file system 1117 cookie. 1118 \return \c B_OK if everything went fine, another error code otherwise. 1119*/ 1120 1121/*! 1122 \fn status_t (*file_system_module_info::close_attr)(fs_volume fs, fs_vnode 1123 vnode, fs_cookie cookie) 1124 \brief Close access to an attribute. 1125 1126 Note that you should not delete the cookie yet, you should do that when the 1127 VFS calls free_attr_cookie(). 1128 1129 \param fs The file system provided cookie to the volume. 1130 \param vnode The file system provided cookie to the vnode. 1131 \param cookie The cookie you associated to this attribute. 1132 \return \c B_OK if everything went fine, another error code otherwise. 1133*/ 1134 1135/*! 1136 \fn status_t (*file_system_module_info::free_attr_cookie)(fs_volume fs, 1137 fs_vnode vnode, fs_cookie cookie) 1138 \brief Free the cookie of an attribute. 1139 1140 The VFS calls this hook when all operations on the attribute have ceased. 1141 1142 \param fs The file system provided cookie to the volume. 1143 \param vnode The file system provided cookie to the vnode. 1144 \param cookie The cookie to the attribute that should be freed. 1145 \return \c B_OK if everything went fine, another error code otherwise. 1146*/ 1147 1148/*! 1149 \fn status_t (*file_system_module_info::read_attr)(fs_volume fs, fs_vnode 1150 vnode, fs_cookie cookie, off_t pos, void *buffer, size_t *length) 1151 \brief Read attribute data associated with \a cookie. 1152 1153 Read until the \a buffer with size \a length is full, or until you are out of 1154 data, in which case you should update \a length. 1155 1156 \param fs The file system provided cookie to the volume. 1157 \param vnode The file system provided cookie to the vnode. 1158 \param cookie The cookie you associated to this attribute. 1159 \param pos The position to start reading from. 1160 \param buffer The buffer the data should be copied in. 1161 \param length The length of the buffer. Update this variable to the actual 1162 amount of bytes read. 1163 \return \c B_OK if everything went fine, another error code otherwise. 1164*/ 1165 1166/*! 1167 \fn status_t (*file_system_module_info::write_attr)(fs_volume fs, fs_vnode 1168 vnode, fs_cookie cookie, off_t pos, const void *buffer, size_t *length) 1169 \brief Write attribute data associated with \a cookie. 1170 1171 \param fs The file system provided cookie to the volume. 1172 \param vnode The file system provided cookie to the vnode. 1173 \param cookie The cookie you associated with this attribute. 1174 \param pos The position to start writing to. 1175 \param buffer The buffer the data should be copied from. 1176 \param length The size of the buffer. Update this variable to the actual 1177 amount of bytes written. 1178 \return \c B_OK if everything went fine, another error code otherwise. 1179*/ 1180 1181/*! 1182 \fn status_t (*file_system_module_info::read_attr_stat)(fs_volume fs, 1183 fs_vnode vnode, fs_cookie cookie, struct stat *stat) 1184 \brief Get the stats for an attribute. 1185 1186 \param fs The file system provided cookie to the volume. 1187 \param vnode The file system provided cookie to the vnode. 1188 \param cookie The cookie you associated with this attribute. 1189 \param stat A pointer to a stat structure you should fill. 1190 \return \c B_OK if everything went fine, another error code otherwise. 1191*/ 1192 1193/*! 1194 \fn status_t (*file_system_module_info::write_attr_stat)(fs_volume fs, 1195 fs_vnode vnode, fs_cookie cookie, const struct stat *stat, int statMask) 1196 \brief Update the stats of an attribute. 1197 1198 \param fs The file system provided cookie to the volume. 1199 \param vnode The file system provided cookie to the vnode. 1200 \param cookie The cookie you associated with this attribute. 1201 \param stat A pointer to the new stats you should write. 1202 \param statMask One or more of the values of #write_stat_mask that tell you 1203 which fields of \a stat are to be updated. 1204 \return \c B_OK if everything went fine, another error code otherwise. 1205*/ 1206 1207/*! 1208 \fn status_t (*file_system_module_info::rename_attr)(fs_volume fs, 1209 fs_vnode fromVnode, const char *fromName, fs_vnode toVnode, 1210 const char *toName) 1211 \brief Rename and/or relocate an attribute. 1212 1213 You should make sure the user has the proper permissions. 1214 1215 \param fs The file system provided cookie associated with this volume. 1216 \param fromVnode The cookie associated with the vnode the attribute currently 1217 is related to. 1218 \param fromName The old name of the attribute. 1219 \param toVnode The cookie associated with the vnode the attribute should be 1220 moved to. This can be the same as \a fromVnode, in which case it only means 1221 the attribute should be renamed. 1222 \param toName The new name of the attribute.This can be the same as 1223 \a fromName, in which case it only means the attribute should be relocated. 1224 \retval B_OK The renaming and/or relocating succeeded. 1225 \retval B_BAD_VALUE One of the supplied parameters were invalid. 1226 \retval B_NOT_ALLOWED The user does not have the proper permissions. 1227 \retval "other errors" Another error condition was encountered. 1228*/ 1229 1230/*! 1231 \fn status_t (*file_system_module_info::remove_attr)(fs_volume fs, 1232 fs_vnode vnode, const char *name) 1233 \brief Remove an attribute. 1234 1235 \param fs The file system provided cookie to the volume. 1236 \param vnode The file system provided cookie to the vnode. 1237 \param name The name of the attribute. 1238 \return \c B_OK if everything went fine, another error code otherwise. 1239*/ 1240 1241//! @} 1242 1243/*! 1244 \name Index Directory and Operation 1245*/ 1246 1247//! @{ 1248 1249/*! 1250 \fn status_t (*file_system_module_info::open_index_dir)(fs_volume fs, 1251 fs_cookie *_cookie) 1252 \brief Open the list of an indeces as a directory. 1253 1254 See \ref concepts "Generic Concepts" on directories and iterators. Basically, 1255 the VFS uses the same way of traversing through indeces as it traverses 1256 through a directory. 1257 1258 \param fs The file system provided cookie to the volume. 1259 \param[out] _cookie Pointer where the file system can store a directory 1260 cookie if the index directory is succesfully opened. 1261 \return \c B_OK if everything went fine, another error code otherwise. 1262*/ 1263 1264/*! 1265 \fn status_t (*file_system_module_info::close_index_dir)(fs_volume fs, 1266 fs_cookie cookie) 1267 \brief Close a 'directory' of indeces. 1268 1269 Note that you should free the cookie in the free_index_dir_cookie() call.: 1270 1271 \param fs The file system provided cookie to the volume. 1272 \param cookie The cookie associated with this 'directory'. 1273 \return B_OK if everything went fine, another error code otherwise. 1274*/ 1275 1276/*! 1277 \fn status_t (*file_system_module_info::free_index_dir_cookie)(fs_volume fs, 1278 fs_cookie cookie) 1279 \brief Free the \a cookie to the index 'directory'. 1280 1281 \param fs The file system provided cookie for the volume. 1282 \param cookie The cookie that should be freed. 1283 \return B_OK if everything went fine, another error code otherwise. 1284*/ 1285 1286/*! 1287 \fn status_t (*file_system_module_info::read_index_dir)(fs_volume fs, 1288 fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num) 1289 \brief Read the next one or more index entries. 1290 1291 This method should perform the same task as read_dir(), except that the '.' 1292 and the '..' entries don't have to be present. 1293*/ 1294 1295/*! 1296 \fn status_t (*file_system_module_info::rewind_index_dir)(fs_volume fs, 1297 fs_cookie cookie) 1298 \brief Reset the index directory cookie to the first entry of the directory. 1299 1300 \param fs The file system provided handle to the volume. 1301 \param cookie The directory cookie as returned by open_index_dir(). 1302 \return \c B_OK if everything went fine, another error code otherwise. 1303*/ 1304 1305/*! 1306 \fn status_t (*file_system_module_info::create_index)(fs_volume fs, 1307 const char *name, uint32 type, uint32 flags) 1308 \brief Create a new index. 1309 1310 \param fs The file system provided handle to the volume. 1311 \param name The name of the new index. 1312 \param type The type of index. BFS implements the following types: 1313 - \c B_INT32_TYPE 1314 - \c B_UINT32_TYPE 1315 - \c B_INT64_TYPE 1316 - \c B_UINT64_TYPE 1317 - \c B_FLOAT_TYPE 1318 - \c B_DOUBLE_TYPE 1319 - \c B_STRING_TYPE 1320 - \c B_MIME_STRING_TYPE 1321 \param flags There are currently no extra flags specified. This parameter can 1322 be ignored. 1323 \return You should return \c B_OK if the creation succeeded, or return an 1324 error otherwise. 1325*/ 1326 1327/*! 1328 \fn status_t (*file_system_module_info::remove_index)(fs_volume fs, 1329 const char *name) 1330 \brief Remove the index with \a name. 1331 1332 \param fs The file system provided handle to the volume. 1333 \param name The name of the index to be removed. 1334 \return You should return \c B_OK if the creation succeeded, or return an 1335 error otherwise. 1336*/ 1337 1338/*! 1339 \fn status_t (*file_system_module_info::read_index_stat)(fs_volume fs, 1340 const char *name, struct stat *stat) 1341 \brief Read the \a stat of the index with a name. 1342 1343 \param fs The file system provided handle to the volume. 1344 \param name The name of the index to be queried. 1345 \param stat A pointer to a structure where you should store the values. 1346 \return You should return \c B_OK if the creation succeeded, or return an 1347 error otherwise. 1348*/ 1349 1350//! @} 1351 1352/*! 1353 \name Query Operations 1354*/ 1355 1356//! @{ 1357 1358/*! 1359 \fn status_t (*file_system_module_info::open_query)(fs_volume fs, 1360 const char *query, uint32 flags, port_id port, uint32 token, 1361 fs_cookie *_cookie) 1362 \brief Open a query as a 'directory'. 1363 1364 TODO: query expressions should be documented and also the format for sending 1365 query updates over the port should be updated. 1366 1367 See \ref concepts "Generic Concepts" on directories and iterators. Basically, 1368 the VFS uses the same way of traversing through indeces as it traverses 1369 through a directory. 1370 1371 \param fs The file system provided cookie to the volume. 1372 \param query The string that represents a query. 1373 \param flags Either one of these flags: 1374 - \c #B_LIVE_QUERY The query is live. When a query is live, it is 1375 constantly updated using the \a port. In this case the file system should 1376 be pro-active. 1377 - \c #B_QUERY_NON_INDEXED When this parameter is provided, the query 1378 should be carried out over the whole file system. This parameter is 1379 provided with the idea that sometimes the indeces can be out of date. If 1380 the requestor for this query requires absolutely everything to be 1381 queried, it will pass this parameter. Of course, if your indeces are 1382 always up to date, you can ignore this parameter. 1383 \param port The id of the port where updates need to be sent to in case the 1384 query is live. 1385 \param token A token that should be attached to the messages sent over the 1386 \a port. 1387 \param[out] _cookie The cookie that will be used as 'directory' to traverse 1388 through the results of the query. 1389 \return You should return \c B_OK if the creation succeeded, or return an 1390 error otherwise. 1391*/ 1392 1393/*! 1394 \fn status_t (*file_system_module_info::close_query)(fs_volume fs, 1395 fs_cookie cookie) 1396 \brief Close a 'directory' of a query. 1397 1398 Note that you should free the cookie in the free_query_cookie() call. 1399 1400 \param fs The file system provided cookie to the volume. 1401 \param cookie The cookie that refers to this query. 1402 \return You should return \c B_OK if the creation succeeded, or return an 1403 error otherwise. 1404*/ 1405 1406/*! 1407 \fn status_t (*file_system_module_info::free_query_cookie)(fs_volume fs, 1408 fs_cookie cookie) 1409 \brief Free a cookie of a query. 1410 1411 \param fs The file system provided cookie to the volume. 1412 \param cookie The cookie that should be freed. 1413 \return You should return \c B_OK if the creation succeeded, or return an 1414 error otherwise. 1415*/ 1416 1417/*! 1418 \fn status_t (*file_system_module_info::read_query)(fs_volume fs, 1419 fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num) 1420 \brief Read the next one or more entries matching the query. 1421 1422 This hook function works pretty much the same way as read_dir(), with the 1423 difference that it doesn't read the entries of a directory, but the entries 1424 matching the given query. 1425 1426 \param fs The volume handle. 1427 \param cookie The query cookie as returned by open_query(). 1428 \param buffer Pointer to a pre-allocated buffer the directory entries shall 1429 be written to. 1430 \param bufferSize The size of \a buffer in bytes. 1431 \param _num Pointer to a pre-allocated variable, when invoked, containing the 1432 number of entries to be read, and into which the number of entries 1433 actually read shall be written. 1434 \return \c B_OK if everything went fine, another error code otherwise. 1435*/ 1436 1437/*! 1438 \fn status_t (*file_system_module_info::rewind_query)(fs_volume fs, 1439 fs_cookie cookie) 1440 \brief Reset the query cookie to the first entry of the results. 1441 1442 \param fs The file system provided handle to the volume. 1443 \param cookie The query cookie as returned by open_query(). 1444 \return \c B_OK if everything went fine, another error code otherwise. 1445*/ 1446 1447//! @} 1448 1449/*! 1450 \name Capability Querying 1451*/ 1452 1453//! @{ 1454 1455/*! 1456 \fn bool (*file_system_module_info::supports_defragmenting)(partition_data 1457 *partition, bool *whileMounted) 1458 \brief Undocumented. TODO. 1459*/ 1460 1461/*! 1462 \fn bool (*file_system_module_info::supports_repairing)(partition_data *partition, 1463 bool checkOnly, bool *whileMounted) 1464 \brief Undocumented. TODO. 1465*/ 1466 1467/*! 1468 \fn bool (*file_system_module_info::supports_resizing)(partition_data *partition, 1469 bool *whileMounted) 1470 \brief Undocumented. TODO. 1471*/ 1472 1473/*! 1474 \fn bool (*file_system_module_info::supports_moving)(partition_data *partition, bool *isNoOp) 1475 \brief Undocumented. TODO. 1476*/ 1477 1478/*! 1479 \fn bool (*file_system_module_info::supports_setting_content_name)(partition_data *partition, 1480 bool *whileMounted) 1481 \brief Undocumented. TODO. 1482*/ 1483 1484/*! 1485 \fn bool (*file_system_module_info::supports_setting_content_parameters)(partition_data *partition, 1486 bool *whileMounted) 1487 \brief Undocumented. TODO. 1488*/ 1489 1490/*! 1491 \fn bool (*file_system_module_info::supports_initializing)(partition_data *partition) 1492 \brief Undocumented. TODO. 1493*/ 1494 1495/*! 1496 \fn bool (*file_system_module_info::validate_resize)(partition_data *partition, off_t *size) 1497 \brief Undocumented. TODO. 1498*/ 1499 1500/*! 1501 \fn bool (*file_system_module_info::validate_move)(partition_data *partition, off_t *start) 1502 \brief Undocumented. TODO. 1503*/ 1504 1505/*! 1506 \fn bool (*file_system_module_info::validate_set_content_name)(partition_data *partition, 1507 char *name) 1508 \brief Undocumented. TODO. 1509*/ 1510 1511/*! 1512 \fn bool (*file_system_module_info::validate_set_content_parameters)(partition_data *partition, 1513 const char *parameters) 1514 \brief Undocumented. TODO. 1515*/ 1516 1517/*! 1518 \fn bool (*file_system_module_info::validate_initialize)(partition_data *partition, char *name, 1519 const char *parameters) 1520 \brief Undocumented. TODO. 1521*/ 1522 1523//! @} 1524 1525/*! 1526 \name Shadow Partition Modification 1527*/ 1528 1529//! @{ 1530 1531/*! 1532 \fn status_t (*file_system_module_info::shadow_changed)(partition_data *partition, 1533 uint32 operation) 1534 \brief Undocumented. TODO. 1535*/ 1536 1537//! @} 1538 1539/*! 1540 \name Special Operations 1541*/ 1542 1543//! @{ 1544 1545/*! 1546 \fn status_t (*file_system_module_info::defragment)(int fd, partition_id partition, 1547 disk_job_id job) 1548 \brief Undocumented. TODO. 1549*/ 1550 1551/*! 1552 \fn status_t (*file_system_module_info::repair)(int fd, partition_id partition, bool checkOnly, 1553 disk_job_id job) 1554 \brief Undocumented. TODO. 1555*/ 1556 1557/*! 1558 \fn status_t (*file_system_module_info::resize)(int fd, partition_id partition, off_t size, 1559 disk_job_id job) 1560 \brief Undocumented. TODO. 1561*/ 1562 1563/*! 1564 \fn status_t (*file_system_module_info::move)(int fd, partition_id partition, off_t offset, 1565 disk_job_id job) 1566 \brief Undocumented. TODO. 1567*/ 1568 1569/*! 1570 \fn status_t (*file_system_module_info::set_content_name)(int fd, partition_id partition, 1571 const char *name, disk_job_id job) 1572 \brief Undocumented. TODO. 1573*/ 1574 1575/*! 1576 \fn status_t (*file_system_module_info::set_content_parameters)(int fd, partition_id partition, 1577 const char *parameters, disk_job_id job) 1578 \brief Undocumented. TODO. 1579*/ 1580 1581/*! 1582 \fn status_t (*file_system_module_info::initialize)(const char *partition, const char *name, 1583 const char *parameters, disk_job_id job) 1584 \brief Undocumented. TODO. 1585*/ 1586 1587//! @} 1588 1589///// Vnode functions ///// 1590 1591/*! 1592 \fn status_t new_vnode(dev_t mountID, ino_t vnodeID, 1593 fs_vnode privateNode) 1594 \brief Create the vnode with ID \a vnodeID and associates it with the 1595 private data handle \a privateNode, but leaves is in an unpublished state. 1596 1597 The effect of the function is similar to publish_vnode(), but the vnode 1598 remains in an unpublished state, with the effect that a subsequent 1599 remove_vnode() will just delete the vnode and not invoke the file system's 1600 \link file_system_module_info::remove_vnode remove_vnode() \endlink when 1601 the final reference is put down. 1602 1603 If the vnode shall be kept, publish_vnode() has to be invoked afterwards to 1604 mark the vnode published. The combined effect is the same as only invoking 1605 publish_vnode(). 1606 1607 You'll usually use this function to secure a vnode ID from being reused 1608 while you are in the process of creating the entry. Note that this function 1609 will panic in case you call it for an existing vnode ID. 1610 1611 The function fails, if the vnode does already exist. 1612 1613 \param mountID The ID of the volume. 1614 \param vnodeID The ID of the node. 1615 \param privateNode The private data handle to be associated with the node. 1616 \return \c B_OK if everything went fine, another error code otherwise. 1617*/ 1618 1619/*! 1620 \fn status_t publish_vnode(dev_t mountID, ino_t vnodeID, 1621 fs_vnode privateNode) 1622 \brief Creates the vnode with ID \a vnodeID and associates it with the 1623 private data handle \a privateNode or just marks it published. 1624 1625 If the vnode does already exist and has been published, the function fails. 1626 If it has not been published yet (i.e. after a successful new_vnode()), the 1627 function just marks the vnode published. If the vnode did not exist at all 1628 before, it is created and published. 1629 1630 If the function is successful, the caller owns a reference to the vnode. A 1631 sequence of new_vnode() and publish_vnode() results in just one reference as 1632 well. The reference can be surrendered by calling put_vnode(). 1633 1634 This call is equivalent to the former R5 new_vnode() function. 1635 1636 \param mountID The ID of the volume. 1637 \param vnodeID The ID of the node. 1638 \param privateNode The private data handle to be associated with the node. 1639 \return \c B_OK if everything went fine, another error code otherwise. 1640*/ 1641 1642/*! 1643 \fn status_t get_vnode(dev_t mountID, ino_t vnodeID, 1644 fs_vnode *_privateNode) 1645 \brief Retrieves the private data handle for the node with the given ID. 1646 1647 If the function is successful, the caller owns a reference to the vnode. The 1648 reference can be surrendered by calling put_vnode(). 1649 1650 \param mountID The ID of the volume. 1651 \param vnodeID The ID of the node. 1652 \param _privateNode Pointer to a pre-allocated variable the private data 1653 handle shall be written to. 1654 \return \c B_OK if everything went fine, another error code otherwise. 1655*/ 1656 1657/*! 1658 \fn status_t put_vnode(dev_t mountID, ino_t vnodeID) 1659 \brief Surrenders a reference to the specified vnode. 1660 \param mountID The ID of the volume. 1661 \param vnodeID The ID of the node. 1662 \return \c B_OK if everything went fine, another error code otherwise. 1663*/ 1664 1665/*! 1666 \fn status_t remove_vnode(dev_t mountID, ino_t vnodeID) 1667 \brief Marks the specified vnode removed. 1668 1669 The caller must own a reference to the vnode or at least ensure that a 1670 reference to the vnode exists. The function does not surrender a reference, 1671 though. 1672 1673 As soon as the last reference to the vnode has been surrendered, the VFS 1674 invokes the file system's 1675 \link file_system_module_info::remove_vnode remove_vnode() \endlink 1676 hook. 1677 1678 \param mountID The ID of the volume. 1679 \param vnodeID The ID of the node. 1680 \return \c B_OK if everything went fine, another error code otherwise. 1681*/ 1682 1683/*! 1684 \fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID); 1685 \brief Clears the "removed" mark of the specified vnode. 1686 1687 The caller must own a reference to the vnode or at least ensure that a 1688 reference to the vnode exists. 1689 1690 The function is usually called when the caller, who has invoked 1691 remove_vnode() before realizes that it is not possible to remove the node 1692 (e.g. due to an error). 1693 1694 \param mountID The ID of the volume. 1695 \param vnodeID The ID of the node. 1696 \return \c B_OK if everything went fine, another error code otherwise. 1697*/ 1698 1699/*! 1700 \fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID, 1701 bool* removed); 1702 \brief Returns whether the specified vnode is marked removed. 1703 1704 The caller must own a reference to the vnode or at least ensure that a 1705 reference to the vnode exists. 1706 1707 \param mountID The ID of the volume. 1708 \param vnodeID The ID of the node. 1709 \param removed Pointer to a pre-allocated variable set to \c true, if the 1710 node is marked removed, to \c false otherwise. 1711 \return \c B_OK if everything went fine, another error code otherwise. 1712*/ 1713 1714///// Notification Functions 1715 1716/*! 1717 \name Notification Functions 1718 1719 The following functions are used to implement the node monitor functionality 1720 in your file system. Whenever one of the below mentioned events occur, you 1721 have to call them. 1722 1723 The node monitor will then notify all registered listeners for the nodes 1724 that changed. 1725*/ 1726 1727/*! 1728 \fn status_t notify_entry_created(dev_t device, ino_t directory, 1729 const char *name, ino_t node) 1730 \brief Notifies listeners that a file system entry has been created. 1731*/ 1732 1733/*! 1734 \fn status_t notify_entry_removed(dev_t device, ino_t directory, 1735 const char *name, ino_t node) 1736 \brief Notifies listeners that a file system entry has been removed. 1737*/ 1738 1739/*! 1740 \fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory, 1741 const char *fromName, ino_t toDirectory, 1742 const char *toName, ino_t node) 1743 \brief Notifies listeners that a file system entry has been moved to 1744 another directory. 1745*/ 1746 1747/*! 1748 \fn status_t notify_stat_changed(dev_t device, ino_t node, 1749 uint32 statFields) 1750 \brief Notifies listeners that certain \a statFields of a file system entry 1751 were updated. 1752*/ 1753 1754/*! 1755 \fn status_t notify_attribute_changed(dev_t device, ino_t node, 1756 const char *attribute, int32 cause) 1757 \brief Notifies listeners that an attribute of a file system entry has been 1758 changed. 1759*/ 1760 1761/*! 1762 \fn status_t notify_query_entry_created(port_id port, int32 token, 1763 dev_t device, ino_t directory, const char *name, 1764 ino_t node) 1765 \brief Notifies listeners that an entry has entered the result set of a live query. 1766*/ 1767 1768/*! 1769 \fn status_t notify_query_entry_removed(port_id port, int32 token, 1770 dev_t device, ino_t directory, const char *name, 1771 ino_t node) 1772 \brief Notifies listeners that an entry has left the result set of a live query. 1773*/ 1774 1775//! @} 1776