# File system API > Mediated Wiki article. Canonical URL: https://mediated.wiki/source/File_system_API > Markdown URL: https://mediated.wiki/source/File_system_API.md > Source: https://en.wikipedia.org/wiki/File_system_API > Source revision: 1353815593 > License: Creative Commons Attribution-ShareAlike 4.0 International (https://creativecommons.org/licenses/by-sa/4.0/) Application programming interface This article includes a list of references, related reading, or external links, but its sources remain unclear because it lacks inline citations. Please help improve this article by introducing more precise citations. (January 2017) (Learn how and when to remove this message) A **file system API** is an [application programming interface](/source/Application_programming_interface) through which a utility or user program requests services of a [file system](/source/File_system). An operating system may provide abstractions for accessing different file systems transparently. Some file system APIs may also include interfaces for maintenance operations, such as creating or initializing a file system, verifying the file system for integrity, and [defragmentation](/source/Defragmentation). Each operating system includes the APIs needed for the file systems it supports. [Microsoft Windows](/source/Microsoft_Windows) has file system APIs for [NTFS](/source/NTFS) and several [FAT](/source/File_Allocation_Table) file systems. [Linux](/source/Linux) systems can include APIs for [ext2](/source/Ext2), [ext3](/source/Ext3), [ReiserFS](/source/ReiserFS), and [Btrfs](/source/Btrfs) to name a few. ## History Some early operating systems were capable of handling only tape and disk file systems. These provided the most basic of interfaces with: - Write, read and position More coordination such as device allocation and deallocation required the addition of: - Open and close As file systems provided more services, more interfaces were defined: - [Metadata](/source/Metadata) management - File system maintenance As additional file system types, hierarchy structure and supported media increased, additional features needed some specialized functions: - Directory management - Data structure management - Record management - [Non-data operations](/source/File_descriptor) Multi-user systems required APIs for: - Sharing - Restricting access - Encryption ## API overviews ### Write, read and position Writing user data to a file system is provided for use directly by the user program or the run-time library. The run-time library for some programming languages may provide type conversion, formatting and blocking. Some file systems provide identification of records by key and may include re-writing an existing record. This operation is sometimes called [PUT](http://www.prycroft6.com.au/misc/download/GC26-3875-0_MVS_DataMgmtSrvcsGde_Aug78OCR.pdf) or PUTX (if the record exists). Reading user data, sometimes called [GET](http://www.prycroft6.com.au/misc/download/GC26-3875-0_MVS_DataMgmtSrvcsGde_Aug78OCR.pdf), may include a direction (forward or reverse) or in the case of a keyed file system, a specific key. As with writing run-time libraries may intercede for the user program. Positioning includes adjusting the location of the next record. This may include skipping forward or reverse as well as positioning to the beginning or end of the file. ### Open and close The *[open](/source/Open_(system_call))* API may be explicitly requested or implicitly invoked upon the issuance of the first operation by a process on an object. It may cause the mounting of removable media, establishing a connection to another host and validating the location and accessibility of the object. It updates system structures to indicate that the object is in use. Usual requirements for requesting access to a file system object include: - The object which is to be accessed (file, directory, media and location) - The intended type of operations to be performed after the open (reads, updates, deletions) Additional information may be necessary, for example: - a password - a declaration that other processes may access the same object while the opening process is using the object (sharing). This may depend on the intent of the other process. In contrast, a declaration that no other process may access the object regardless of the other processes intent (exclusive use). These are requested via a programming language library which may provide coordination among modules in the process in addition to forwarding the request to the file system. It must be expected that something may go wrong during the processing of the open: - The object or intent may be improperly specified (the name may include an unacceptable character or the intent is unrecognized). - The process may be prohibited from accessing the object (it may be only accessible by a group or specific user). - The file system may be unable to create or update structures required to coordinate activities among users. - In the case of a new (or replacement) object, there may not be sufficient capacity on the media. Depending on the programming language, additional specifications in the open may establish the modules to handle these conditions. Some libraries specify a library module to the file system permitting analysis should the opening program be unable to perform any meaningful action as a result of a failure. *[Close](/source/Close_(system_call))* may cause dismounting or ejecting removable media and updating library and file system structures to indicate that the object is no longer in use. The minimal specification to the close references the object. Additionally, some file systems provide specifying a disposition of the object which may indicate the object is to be discarded and no longer be part of the file system. Similar to the open, it must be expected that something may go wrong: - The specification of the object may be incorrect. - There may not be sufficient capacity on the media to save any data being buffered or to output a structure indicating that the object was successfully updated. - A device error may occur on the media where the object is stored while writing buffered data, the completion structure or updating metadata related to the object (for example last access time). - A specification to release the object may be inconsistent with other processes still using the object. Considerations for handling a failure are similar to those of the open. ### Metadata management Information about the data in a file is called metadata. Some of the metadata is maintained by the file system, for example last-modification date (and various other dates depending on the file system), location of the beginning of the file, the size of the file and if the file system backup utility has saved the current version of the files. These items cannot usually be altered by a user program. Additional metadata supported by some file systems may include the owner of the file, the group to which the file belongs as well as permissions and access control (i.e. what access and updates various users or groups may perform), and whether the file is normally visible when the directory is listed. These items are usually modifiable by file system utilities which may be executed by the owner. Some applications store more metadata. For images the metadata may include the camera model and settings used to take the photo. For audio files, the metadata may include the album, artist who recorded the recording and comments about the recording which may be specific to a particular copy of the file (i.e. different copies of the same recording may have different comments as update by the owner of the file). Documents may include items like checked-by, approved-by, etc. ### Directory management Renaming a file, moving a file (or a subdirectory) from one directory to another and deleting a file are examples of the operations provide by the file system for the management of directories. Metadata operations such as permitting or restricting access the a directory by various users or groups of users are usually included. ### File-system maintenance As a file system is used directories, files and records may be added, deleted or modified. This usually causes inefficiencies in the underlying data structures. Things like logically sequential blocks distributed across the media in a way that causes excessive repositioning, partially used even empty blocks included in linked structures. Incomplete structures or other inconsistencies may be caused by device or media errors, inadequate time between detection of impending loss of power and actual power loss, improper system shutdown or media removal, and on very rare occasions file system coding errors. Specialized routines in the file system are included to optimize or repair these structures. They are not usually invoked by the user directly but triggered within the file system itself. Internal counters of the number of levels of structures, number of inserted objects may be compared against thresholds. These may cause user access to be suspended to a specific structure (usually to the displeasure of the user or users effected) or may be started as low priority asynchronous tasks or they may be deferred to a time of low user activity. Sometimes these routines are invoked or scheduled by the system manager or as in the case of defragmentation. ## Kernel-level API The API is *kernel-level* when the kernel not only provides the interfaces for the file-system developers but is also the space in which the file-system code resides. It differs with the old schema in that the kernel itself uses its own facilities to talk with the file-system driver and vice versa, as contrary to the kernel being the one that handles the file-system layout and the file system the one that directly access the hardware. It is not the cleanest scheme but resolves the difficulties of major rewrite that has the old scheme. With modular kernels it allows adding file systems as any kernel module, even third party ones. With non-modular kernels however it requires the kernel to be recompiled with the new file-system code (and in closed-source kernels, this makes third-party file systems impossible). [Unixes](/source/Unix) and [Unix-like](/source/Unix-like) systems such as Linux have used this modular scheme. There is a variation of this scheme used in [MS-DOS](/source/MS-DOS) (DOS 4.0 onward) and compatibles to support CD-ROM and network file systems. Instead of adding code to the kernel, as in the old scheme, or using kernel facilities as in the kernel-based scheme, it traps all calls to a file and identifies if it should be redirected to the kernel's equivalent function or if it has to be handled by the specific file-system driver, and the file-system driver directly accesses the disk contents using low-level [BIOS](/source/BIOS) functions. ## Driver-based API The API is *driver-based* when the kernel provides facilities but the file system code resides totally external to the kernel (not even as a module of a modular kernel). It is a cleaner scheme as the file-system code is totally independent, it allows file systems to be created for closed-source kernels and online file system additions or removals from the system. Examples of this scheme are the [Windows NT](/source/Windows_NT) and [OS/2](/source/OS%2F2) respective [Installable File Systems](/source/Installable_File_System) (IFSs). ## Mixed kernel-driver-based API In this API, all file systems are in the kernel, like in kernel-based APIs, but they are automatically trapped by another API, that is driver-based, by the OS. ## User space API The API is in the [user space](/source/User_space) when the file system does not directly use kernel facilities but accesses disks using high-level operating system functions and provides functions in a [library](/source/Library_(computing)) that a series of utilities use to access the file system. This is useful for handling disk images. The advantage is that a file system can be made portable between operating systems as the high-level operating system functions it uses can be as common as ANSI C, but the disadvantage is that the API is unique to each application that implements one. Examples of this scheme are the [hfsutils](http://www.mars.org/home/rob/proj/hfs/) and the [adflib](https://github.com/adflib/ADFlib). ## Interoperatibility between file system APIs As all disk file systems need equivalent functions provided by the kernel, it is possible to easily port file-system code from one API to another, even if they are of different types. ## See also - [Comparison of file systems](/source/Comparison_of_file_systems) - [Filename extension](/source/Filename_extension) - [Filing Open Service Interface Definition](/source/Filing_Open_Service_Interface_Definition) (OSID) - [List of file systems](/source/List_of_file_systems) - [Virtual file system](/source/Virtual_file_system) ## References ## Sources - Custer, Helen (1993). *Inside Windows NT*. [Microsoft Press](/source/Microsoft_Press). [ISBN](/source/ISBN_(identifier)) [1-55615-481-X](https://en.wikipedia.org/wiki/Special:BookSources/1-55615-481-X). - Custer, Helen (1994). *Inside Windows NT File System*. Microsoft Press. [ISBN](/source/ISBN_(identifier)) [1-55615-660-X](https://en.wikipedia.org/wiki/Special:BookSources/1-55615-660-X). - Nagar, Rajeev (1997). *Windows NT File System Internals, A Developer's Guide*. [O'Reilly Media](/source/O'Reilly_Media). [ISBN](/source/ISBN_(identifier)) [1-56592-249-2](https://en.wikipedia.org/wiki/Special:BookSources/1-56592-249-2). - Pate, Steve D. (2003). *UNIX Filesystems: Evolution, Design, and Implementation*. [Wiley](/source/Wiley_(publisher)). [ISBN](/source/ISBN_(identifier)) [0-471-16483-6](https://en.wikipedia.org/wiki/Special:BookSources/0-471-16483-6). ## External links - [A Tour of the Linux VFS](http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html) - [Microsoft's IFSKit](http://www.microsoft.com/whdc/devtools/ifskit/default.mspx) v t e File systems Comparison of file systems distributed Unix filesystem Disk and non-rotating ADFS AdvFS Amiga FFS Amiga OFS APFS AthFS bcachefs BFS Be File System Boot File System Byte File System (z/VM) Btrfs CVFS CXFS DFS EFS Encrypting File System Extent File System Episode ext ext2 ext3 ext4 FAT exFAT Files-11 Fossil GPFS HAMMER HAMMER2 HFS (Classic Mac OS) HFS (MVS) HFS+ HPFS HTFS JFS LFS MFS Macintosh File System TiVo Media File System MINIX NetWare File System Next3 NILFS NILFS2 NSS NTFS OneFS OpenZFS PFS QFS QNX4FS ReFS ReiserFS Reiser4 Reliance Reliance Nitro RFS SFS Shared File System (VM) Smart File System SNFS Soup (Apple) Tux3 UBIFS UFS/UFS2 soft updates WAPBL VxFS WAFL Xiafs XFS Xsan zFS (z/OS) ZFS (Sun) Optical disc HSF ISO 9660 ISO 13490 UDF Flash memory and SSD APFS FAT exFAT TFAT EROFS F2FS JFS NVFS host-side wear leveling CHFS JFFS JFFS2 LogFS NILFS NILFS2 YAFFS UBIFS Distributed parallel BeeGFS Ceph CXFS GFS2 Google File System OCFS2 OrangeFS PVFS QFS Xsan more... NAS 9P AFS (OpenAFS) AFP Coda DFS Google File System GPFS Lustre NCP NFS POHMELFS Hadoop SMB (CIFS) SSHFS more... Specialized Aufs AXFS Boot File System Compact Disc File System cramfs Davfs2 EROFS FTPFS FUSE Lnfs LTFS NOVA MVFS SquashFS UMSDOS OverlayFS UnionFS Pseudo configfs devfs debugfs kernfs procfs specfs sysfs tmpfs WinFS Encrypted eCryptfs EncFS EFS Rubberhose SSHFS ZFS Types Clustered Global Grid Self-certifying Flash Journaling Log-structured Object Record-oriented Semantic Steganographic Synthetic Versioning Features Case preservation Copy-on-write Data deduplication Data scrubbing Execute in place Extent File attribute Extended file attributes File change log Fork Inode Links Hard Symbolic Access control Access-control list Filesystem-level encryption Permissions Modes Sticky bit Interfaces File manager File system API Installable File System Virtual file system Lists Cryptographic Default Log-structured Layouts Master Boot Record GUID Partition Table Apple Partition Map --- Adapted from the Wikipedia article [File system API](https://en.wikipedia.org/wiki/File_system_API) by Wikipedia contributors ([contributor history](https://en.wikipedia.org/wiki/File_system_API?action=history)). Available under [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/). Changes may have been made.