diff options
Diffstat (limited to 'Documentation/filesystems')
33 files changed, 409 insertions, 370 deletions
diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst index 2995279ddc24..7b5964bc8865 100644 --- a/Documentation/filesystems/9p.rst +++ b/Documentation/filesystems/9p.rst @@ -18,7 +18,7 @@ and Maya Gokhale. Additional development by Greg Watson The best detailed explanation of the Linux implementation and applications of the 9p client is available in the form of a USENIX paper: - http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html + https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html Other applications are described in the following papers: diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst index cada9464d6bd..0abb155ac666 100644 --- a/Documentation/filesystems/afs.rst +++ b/Documentation/filesystems/afs.rst @@ -190,7 +190,7 @@ Security Secure operations are initiated by acquiring a key using the klog program. A very primitive klog program is available at: - http://people.redhat.com/~dhowells/rxrpc/klog.c + https://people.redhat.com/~dhowells/rxrpc/klog.c This should be compiled by:: diff --git a/Documentation/filesystems/autofs-mount-control.rst b/Documentation/filesystems/autofs-mount-control.rst index 2903aed92316..bf4b511cdbe8 100644 --- a/Documentation/filesystems/autofs-mount-control.rst +++ b/Documentation/filesystems/autofs-mount-control.rst @@ -391,7 +391,7 @@ variation uses the path and optionally in.type field of struct args_ismountpoint set to an autofs mount type. The call returns 1 if this is a mount point and sets out.devid field to the device number of the mount and out.magic field to the relevant super block magic number (described below) or 0 if -it isn't a mountpoint. In both cases the the device number (as returned +it isn't a mountpoint. In both cases the device number (as returned by new_encode_dev()) is returned in out.devid field. If supplied with a file descriptor we're looking for a specific mount, @@ -399,12 +399,12 @@ not necessarily at the top of the mounted stack. In this case the path the descriptor corresponds to is considered a mountpoint if it is itself a mountpoint or contains a mount, such as a multi-mount without a root mount. In this case we return 1 if the descriptor corresponds to a mount -point and and also returns the super magic of the covering mount if there +point and also returns the super magic of the covering mount if there is one or 0 if it isn't a mountpoint. If a path is supplied (and the ioctlfd field is set to -1) then the path is looked up and is checked to see if it is the root of a mount. If a type is also given we are looking for a particular autofs mount and if -a match isn't found a fail is returned. If the the located path is the +a match isn't found a fail is returned. If the located path is the root of a mount 1 is returned along with the super magic of the mount or 0 otherwise. diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst index 65d3db476765..e58bc1fd312a 100644 --- a/Documentation/filesystems/caching/cachefiles.rst +++ b/Documentation/filesystems/caching/cachefiles.rst @@ -348,7 +348,7 @@ data cached therein; nor is it permitted to create new files in the cache. There are policy source files available in: - http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 + https://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 and later versions. In that tarball, see the files:: diff --git a/Documentation/filesystems/caching/operations.rst b/Documentation/filesystems/caching/operations.rst index f7ddcc028939..9983e1675447 100644 --- a/Documentation/filesystems/caching/operations.rst +++ b/Documentation/filesystems/caching/operations.rst @@ -27,7 +27,7 @@ data storage and retrieval routines. Its operations are represented by fscache_operation structs, though these are usually embedded into some other structure. -This facility is available to and expected to be be used by the cache backends, +This facility is available to and expected to be used by the cache backends, and FS-Cache will create operations and pass them off to the appropriate cache backend for completion. diff --git a/Documentation/filesystems/coda.rst b/Documentation/filesystems/coda.rst index 84c860c89887..bdde7e4e010b 100644 --- a/Documentation/filesystems/coda.rst +++ b/Documentation/filesystems/coda.rst @@ -524,7 +524,7 @@ kernel support. Description This call is made to determine the ViceFid and filetype of - a directory entry. The directory entry requested carries name name + a directory entry. The directory entry requested carries name 'name' and Venus will search the directory identified by cfs_lookup_in.VFid. The result may indicate that the name does not exist, or that difficulty was encountered in finding it (e.g. due to disconnection). @@ -886,7 +886,7 @@ kernel support. none Description - Remove the directory with name name from the directory + Remove the directory with name 'name' from the directory identified by VFid. .. Note:: The attributes of the parent directory should be returned since diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst index f8941954c667..1d3d6f4a82a9 100644 --- a/Documentation/filesystems/configfs.rst +++ b/Documentation/filesystems/configfs.rst @@ -226,7 +226,7 @@ filename. configfs_attribute->ca_mode specifies the file permissions. If an attribute is readable and provides a ->show method, that method will be called whenever userspace asks for a read(2) on the attribute. If an attribute is writable and provides a ->store method, that method will be -be called whenever userspace asks for a write(2) on the attribute. +called whenever userspace asks for a write(2) on the attribute. struct configfs_bin_attribute ============================= diff --git a/Documentation/filesystems/debugfs.rst b/Documentation/filesystems/debugfs.rst index 1da7a4b7383d..728ab57a611a 100644 --- a/Documentation/filesystems/debugfs.rst +++ b/Documentation/filesystems/debugfs.rst @@ -185,13 +185,17 @@ byte offsets over a base for the register block. If you want to dump an u32 array in debugfs, you can create file with:: + struct debugfs_u32_array { + u32 *array; + u32 n_elements; + }; + void debugfs_create_u32_array(const char *name, umode_t mode, struct dentry *parent, - u32 *array, u32 elements); + struct debugfs_u32_array *array); -The "array" argument provides data, and the "elements" argument is -the number of elements in the array. Note: Once array is created its -size can not be changed. +The "array" argument wraps a pointer to the array's data and the number +of its elements. Note: Once array is created its size can not be changed. There is a helper function to create device related seq_file:: diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index de12016ee419..504ba940c36c 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -28,7 +28,7 @@ RENAME_EXCHANGE in flags argument) lock both. In any case, if the target already exists, lock it. If the source is a non-directory, lock it. If we need to lock both, lock them in inode pointer order. Then call the method. All locks are exclusive. -NB: we might get away with locking the the source (and target in exchange +NB: we might get away with locking the source (and target in exchange case) shared. 5) link creation. Locking rules: @@ -56,7 +56,7 @@ rules: * call the method. All ->i_rwsem are taken exclusive. Again, we might get away with locking -the the source (and target in exchange case) shared. +the source (and target in exchange case) shared. The rules above obviously guarantee that all directories that are going to be read, modified or removed by method will be locked by caller. diff --git a/Documentation/filesystems/dlmfs.rst b/Documentation/filesystems/dlmfs.rst index 68daaa7facf9..28dd41a63be2 100644 --- a/Documentation/filesystems/dlmfs.rst +++ b/Documentation/filesystems/dlmfs.rst @@ -12,7 +12,7 @@ dlmfs is built with OCFS2 as it requires most of its infrastructure. :Project web page: http://ocfs2.wiki.kernel.org :Tools web page: https://github.com/markfasheh/ocfs2-tools -:OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ +:OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/ All code copyright 2005 Oracle except when otherwise noted. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 099d45ac8d8f..ec8d99703ecb 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -101,164 +101,172 @@ Mount Options ============= -====================== ============================================================ -background_gc=%s Turn on/off cleaning operations, namely garbage - collection, triggered in background when I/O subsystem is - idle. If background_gc=on, it will turn on the garbage - collection and if background_gc=off, garbage collection - will be turned off. If background_gc=sync, it will turn - on synchronous garbage collection running in background. - Default value for this option is on. So garbage - collection is on by default. -disable_roll_forward Disable the roll-forward recovery routine -norecovery Disable the roll-forward recovery routine, mounted read- - only (i.e., -o ro,disable_roll_forward) -discard/nodiscard Enable/disable real-time discard in f2fs, if discard is - enabled, f2fs will issue discard/TRIM commands when a - segment is cleaned. -no_heap Disable heap-style segment allocation which finds free - segments for data from the beginning of main area, while - for node from the end of main area. -nouser_xattr Disable Extended User Attributes. Note: xattr is enabled - by default if CONFIG_F2FS_FS_XATTR is selected. -noacl Disable POSIX Access Control List. Note: acl is enabled - by default if CONFIG_F2FS_FS_POSIX_ACL is selected. -active_logs=%u Support configuring the number of active logs. In the - current design, f2fs supports only 2, 4, and 6 logs. - Default number is 6. -disable_ext_identify Disable the extension list configured by mkfs, so f2fs - does not aware of cold files such as media files. -inline_xattr Enable the inline xattrs feature. -noinline_xattr Disable the inline xattrs feature. -inline_xattr_size=%u Support configuring inline xattr size, it depends on - flexible inline xattr feature. -inline_data Enable the inline data feature: New created small(<~3.4k) - files can be written into inode block. -inline_dentry Enable the inline dir feature: data in new created - directory entries can be written into inode block. The - space of inode block which is used to store inline - dentries is limited to ~3.4k. -noinline_dentry Disable the inline dentry feature. -flush_merge Merge concurrent cache_flush commands as much as possible - to eliminate redundant command issues. If the underlying - device handles the cache_flush command relatively slowly, - recommend to enable this option. -nobarrier This option can be used if underlying storage guarantees - its cached data should be written to the novolatile area. - If this option is set, no cache_flush commands are issued - but f2fs still guarantees the write ordering of all the - data writes. -fastboot This option is used when a system wants to reduce mount - time as much as possible, even though normal performance - can be sacrificed. -extent_cache Enable an extent cache based on rb-tree, it can cache - as many as extent which map between contiguous logical - address and physical address per inode, resulting in - increasing the cache hit ratio. Set by default. -noextent_cache Disable an extent cache based on rb-tree explicitly, see - the above extent_cache mount option. -noinline_data Disable the inline data feature, inline data feature is - enabled by default. -data_flush Enable data flushing before checkpoint in order to - persist data of regular and symlink. -reserve_root=%d Support configuring reserved space which is used for - allocation from a privileged user with specified uid or - gid, unit: 4KB, the default limit is 0.2% of user blocks. -resuid=%d The user ID which may use the reserved blocks. -resgid=%d The group ID which may use the reserved blocks. -fault_injection=%d Enable fault injection in all supported types with - specified injection rate. -fault_type=%d Support configuring fault injection type, should be - enabled with fault_injection option, fault type value - is shown below, it supports single or combined type. - - =================== =========== - Type_Name Type_Value - =================== =========== - FAULT_KMALLOC 0x000000001 - FAULT_KVMALLOC 0x000000002 - FAULT_PAGE_ALLOC 0x000000004 - FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 - FAULT_ALLOC_NID 0x000000020 - FAULT_ORPHAN 0x000000040 - FAULT_BLOCK 0x000000080 - FAULT_DIR_DEPTH 0x000000100 - FAULT_EVICT_INODE 0x000000200 - FAULT_TRUNCATE 0x000000400 - FAULT_READ_IO 0x000000800 - FAULT_CHECKPOINT 0x000001000 - FAULT_DISCARD 0x000002000 - FAULT_WRITE_IO 0x000004000 - =================== =========== -mode=%s Control block allocation mode which supports "adaptive" - and "lfs". In "lfs" mode, there should be no random - writes towards main area. -io_bits=%u Set the bit size of write IO requests. It should be set - with "mode=lfs". -usrquota Enable plain user disk quota accounting. -grpquota Enable plain group disk quota accounting. -prjquota Enable plain project quota accounting. -usrjquota=<file> Appoint specified file and type during mount, so that quota -grpjquota=<file> information can be properly updated during recovery flow, -prjjquota=<file> <quota file>: must be in root directory; -jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. -offusrjquota Turn off user journelled quota. -offgrpjquota Turn off group journelled quota. -offprjjquota Turn off project journelled quota. -quota Enable plain user disk quota accounting. -noquota Disable all plain disk quota option. -whint_mode=%s Control which write hints are passed down to block - layer. This supports "off", "user-based", and - "fs-based". In "off" mode (default), f2fs does not pass - down hints. In "user-based" mode, f2fs tries to pass - down hints given by users. And in "fs-based" mode, f2fs - passes down hints with its policy. -alloc_mode=%s Adjust block allocation policy, which supports "reuse" - and "default". -fsync_mode=%s Control the policy of fsync. Currently supports "posix", - "strict", and "nobarrier". In "posix" mode, which is - default, fsync will follow POSIX semantics and does a - light operation to improve the filesystem performance. - In "strict" mode, fsync will be heavy and behaves in line - with xfs, ext4 and btrfs, where xfstest generic/342 will - pass, but the performance will regress. "nobarrier" is - based on "posix", but doesn't issue flush command for - non-atomic files likewise "nobarrier" mount option. +======================== ============================================================ +background_gc=%s Turn on/off cleaning operations, namely garbage + collection, triggered in background when I/O subsystem is + idle. If background_gc=on, it will turn on the garbage + collection and if background_gc=off, garbage collection + will be turned off. If background_gc=sync, it will turn + on synchronous garbage collection running in background. + Default value for this option is on. So garbage + collection is on by default. +disable_roll_forward Disable the roll-forward recovery routine +norecovery Disable the roll-forward recovery routine, mounted read- + only (i.e., -o ro,disable_roll_forward) +discard/nodiscard Enable/disable real-time discard in f2fs, if discard is + enabled, f2fs will issue discard/TRIM commands when a + segment is cleaned. +no_heap Disable heap-style segment allocation which finds free + segments for data from the beginning of main area, while + for node from the end of main area. +nouser_xattr Disable Extended User Attributes. Note: xattr is enabled + by default if CONFIG_F2FS_FS_XATTR is selected. +noacl Disable POSIX Access Control List. Note: acl is enabled + by default if CONFIG_F2FS_FS_POSIX_ACL is selected. +active_logs=%u Support configuring the number of active logs. In the + current design, f2fs supports only 2, 4, and 6 logs. + Default number is 6. +disable_ext_identify Disable the extension list configured by mkfs, so f2fs + does not aware of cold files such as media files. +inline_xattr Enable the inline xattrs feature. +noinline_xattr Disable the inline xattrs feature. +inline_xattr_size=%u Support configuring inline xattr size, it depends on + flexible inline xattr feature. +inline_data Enable the inline data feature: New created small(<~3.4k) + files can be written into inode block. +inline_dentry Enable the inline dir feature: data in new created + directory entries can be written into inode block. The + space of inode block which is used to store inline + dentries is limited to ~3.4k. +noinline_dentry Disable the inline dentry feature. +flush_merge Merge concurrent cache_flush commands as much as possible + to eliminate redundant command issues. If the underlying + device handles the cache_flush command relatively slowly, + recommend to enable this option. +nobarrier This option can be used if underlying storage guarantees + its cached data should be written to the novolatile area. + If this option is set, no cache_flush commands are issued + but f2fs still guarantees the write ordering of all the + data writes. +fastboot This option is used when a system wants to reduce mount + time as much as possible, even though normal performance + can be sacrificed. +extent_cache Enable an extent cache based on rb-tree, it can cache + as many as extent which map between contiguous logical + address and physical address per inode, resulting in + increasing the cache hit ratio. Set by default. +noextent_cache Disable an extent cache based on rb-tree explicitly, see + the above extent_cache mount option. +noinline_data Disable the inline data feature, inline data feature is + enabled by default. +data_flush Enable data flushing before checkpoint in order to + persist data of regular and symlink. +reserve_root=%d Support configuring reserved space which is used for + allocation from a privileged user with specified uid or + gid, unit: 4KB, the default limit is 0.2% of user blocks. +resuid=%d The user ID which may use the reserved blocks. +resgid=%d The group ID which may use the reserved blocks. +fault_injection=%d Enable fault injection in all supported types with + specified injection rate. +fault_type=%d Support configuring fault injection type, should be + enabled with fault_injection option, fault type value + is shown below, it supports single or combined type. + + =================== =========== + Type_Name Type_Value + =================== =========== + FAULT_KMALLOC 0x000000001 + FAULT_KVMALLOC 0x000000002 + FAULT_PAGE_ALLOC 0x000000004 + FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 + FAULT_ALLOC_NID 0x000000020 + FAULT_ORPHAN 0x000000040 + FAULT_BLOCK 0x000000080 + FAULT_DIR_DEPTH 0x000000100 + FAULT_EVICT_INODE 0x000000200 + FAULT_TRUNCATE 0x000000400 + FAULT_READ_IO 0x000000800 + FAULT_CHECKPOINT 0x000001000 + FAULT_DISCARD 0x000002000 + FAULT_WRITE_IO 0x000004000 + =================== =========== +mode=%s Control block allocation mode which supports "adaptive" + and "lfs". In "lfs" mode, there should be no random + writes towards main area. +io_bits=%u Set the bit size of write IO requests. It should be set + with "mode=lfs". +usrquota Enable plain user disk quota accounting. +grpquota Enable plain group disk quota accounting. +prjquota Enable plain project quota accounting. +usrjquota=<file> Appoint specified file and type during mount, so that quota +grpjquota=<file> information can be properly updated during recovery flow, +prjjquota=<file> <quota file>: must be in root directory; +jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. +offusrjquota Turn off user journelled quota. +offgrpjquota Turn off group journelled quota. +offprjjquota Turn off project journelled quota. +quota Enable plain user disk quota accounting. +noquota Disable all plain disk quota option. +whint_mode=%s Control which write hints are passed down to block + layer. This supports "off", "user-based", and + "fs-based". In "off" mode (default), f2fs does not pass + down hints. In "user-based" mode, f2fs tries to pass + down hints given by users. And in "fs-based" mode, f2fs + passes down hints with its policy. +alloc_mode=%s Adjust block allocation policy, which supports "reuse" + and "default". +fsync_mode=%s Control the policy of fsync. Currently supports "posix", + "strict", and "nobarrier". In "posix" mode, which is + default, fsync will follow POSIX semantics and does a + light operation to improve the filesystem performance. + In "strict" mode, fsync will be heavy and behaves in line + with xfs, ext4 and btrfs, where xfstest generic/342 will + pass, but the performance will regress. "nobarrier" is + based on "posix", but doesn't issue flush command for + non-atomic files likewise "nobarrier" mount option. test_dummy_encryption test_dummy_encryption=%s - Enable dummy encryption, which provides a fake fscrypt - context. The fake fscrypt context is used by xfstests. - The argument may be either "v1" or "v2", in order to - select the corresponding fscrypt policy version. -checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" - to reenable checkpointing. Is enabled by default. While - disabled, any unmounting or unexpected shutdowns will cause - the filesystem contents to appear as they did when the - filesystem was mounted with that option. - While mounting with checkpoint=disabled, the filesystem must - run garbage collection to ensure that all available space can - be used. If this takes too much time, the mount may return - EAGAIN. You may optionally add a value to indicate how much - of the disk you would be willing to temporarily give up to - avoid additional garbage collection. This can be given as a - number of blocks, or as a percent. For instance, mounting - with checkpoint=disable:100% would always succeed, but it may - hide up to all remaining free space. The actual space that - would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable - This space is reclaimed once checkpoint=enable. -compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", - "lz4", "zstd" and "lzo-rle" algorithm. -compress_log_size=%u Support configuring compress cluster size, the size will - be 4KB * (1 << %u), 16KB is minimum size, also it's - default size. -compress_extension=%s Support adding specified extension, so that f2fs can enable - compression on those corresponding files, e.g. if all files - with '.ext' has high compression rate, we can set the '.ext' - on compression extension list and enable compression on - these file by default rather than to enable it via ioctl. - For other files, we can still enable compression via ioctl. -====================== ============================================================ + Enable dummy encryption, which provides a fake fscrypt + context. The fake fscrypt context is used by xfstests. + The argument may be either "v1" or "v2", in order to + select the corresponding fscrypt policy version. +checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" + to reenable checkpointing. Is enabled by default. While + disabled, any unmounting or unexpected shutdowns will cause + the filesystem contents to appear as they did when the + filesystem was mounted with that option. + While mounting with checkpoint=disabled, the filesystem must + run garbage collection to ensure that all available space can + be used. If this takes too much time, the mount may return + EAGAIN. You may optionally add a value to indicate how much + of the disk you would be willing to temporarily give up to + avoid additional garbage collection. This can be given as a + number of blocks, or as a percent. For instance, mounting + with checkpoint=disable:100% would always succeed, but it may + hide up to all remaining free space. The actual space that + would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable + This space is reclaimed once checkpoint=enable. +compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", + "lz4", "zstd" and "lzo-rle" algorithm. +compress_log_size=%u Support configuring compress cluster size, the size will + be 4KB * (1 << %u), 16KB is minimum size, also it's + default size. +compress_extension=%s Support adding specified extension, so that f2fs can enable + compression on those corresponding files, e.g. if all files + with '.ext' has high compression rate, we can set the '.ext' + on compression extension list and enable compression on + these file by default rather than to enable it via ioctl. + For other files, we can still enable compression via ioctl. + Note that, there is one reserved special extension '*', it + can be set to enable compression for all files. +inlinecrypt When possible, encrypt/decrypt the contents of encrypted + files using the blk-crypto framework rather than + filesystem-layer encryption. This allows the use of + inline encryption hardware. The on-disk format is + unaffected. For more details, see + Documentation/block/inline-encryption.rst. +======================== ============================================================ Debugfs Entries =============== @@ -737,8 +745,8 @@ Compression implementation - In order to eliminate write amplification during overwrite, F2FS only support compression on write-once file, data can be compressed only when - all logical blocks in file are valid and cluster compress ratio is lower - than specified threshold. + all logical blocks in cluster contain valid data and compress ratio of + cluster data is lower than specified threshold. - To enable compression on regular inode, there are three ways: diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index f517af8ec11c..423c5a0daf45 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -1158,7 +1158,7 @@ setxattr() because of the special semantics of the encryption xattr. were to be added to or removed from anything other than an empty directory.) These structs are defined as follows:: - #define FS_KEY_DERIVATION_NONCE_SIZE 16 + #define FSCRYPT_FILE_NONCE_SIZE 16 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_context_v1 { @@ -1167,7 +1167,7 @@ directory.) These structs are defined as follows:: u8 filenames_encryption_mode; u8 flags; u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; - u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; + u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 @@ -1178,7 +1178,7 @@ directory.) These structs are defined as follows:: u8 flags; u8 __reserved[4]; u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; - u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; + u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; The context structs contain the same information as the corresponding @@ -1204,6 +1204,18 @@ buffer. Some filesystems, such as UBIFS, already use temporary buffers regardless of encryption. Other filesystems, such as ext4 and F2FS, have to allocate bounce pages specially for encryption. +Fscrypt is also able to use inline encryption hardware instead of the +kernel crypto API for en/decryption of file contents. When possible, +and if directed to do so (by specifying the 'inlinecrypt' mount option +for an ext4/F2FS filesystem), it adds encryption contexts to bios and +uses blk-crypto to perform the en/decryption instead of making use of +the above read/write path changes. Of course, even if directed to +make use of inline encryption, fscrypt will only be able to do so if +either hardware inline encryption support is available for the +selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK +is selected. If neither is the case, fscrypt will fall back to using +the above mentioned read/write path changes for en/decryption. + Filename hashing and encoding ----------------------------- @@ -1250,11 +1262,14 @@ Tests To test fscrypt, use xfstests, which is Linux's de facto standard filesystem test suite. First, run all the tests in the "encrypt" -group on the relevant filesystem(s). For example, to test ext4 and +group on the relevant filesystem(s). One can also run the tests +with the 'inlinecrypt' mount option to test the implementation for +inline encryption support. For example, to test ext4 and f2fs encryption using `kvm-xfstests <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: kvm-xfstests -c ext4,f2fs -g encrypt + kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt UBIFS encryption can also be tested this way, but it should be done in a separate command, and it takes some time for kvm-xfstests to set up @@ -1276,6 +1291,7 @@ This tests the encrypted I/O paths more thoroughly. To do this with kvm-xfstests, use the "encrypt" filesystem configuration:: kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto + kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt Because this runs many more tests than "-g encrypt" does, it takes much longer to run; so also consider using `gce-xfstests @@ -1283,3 +1299,4 @@ much longer to run; so also consider using `gce-xfstests instead of kvm-xfstests:: gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto + gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index a95536b6443c..6c8944f6f0f7 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -659,7 +659,7 @@ weren't already directly answered in other parts of this document. retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow. - - Rebuilding the the Merkle tree after every write, which would be + - Rebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex. diff --git a/Documentation/filesystems/hfs.rst b/Documentation/filesystems/hfs.rst index ab17a005e9b1..776015c80e3f 100644 --- a/Documentation/filesystems/hfs.rst +++ b/Documentation/filesystems/hfs.rst @@ -76,7 +76,7 @@ Creating HFS filesystems The hfsutils package from Robert Leslie contains a program called hformat that can be used to create HFS filesystem. See -<http://www.mars.org/home/rob/proj/hfs/> for details. +<https://www.mars.org/home/rob/proj/hfs/> for details. Credits diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst index 0db152278572..7e0dd2f4373e 100644 --- a/Documentation/filesystems/hpfs.rst +++ b/Documentation/filesystems/hpfs.rst @@ -7,7 +7,7 @@ Read/Write HPFS 2.09 1998-2004, Mikulas Patocka :email: mikulas@artax.karlin.mff.cuni.cz -:homepage: http://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi +:homepage: https://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi Credits ======= diff --git a/Documentation/filesystems/journalling.rst b/Documentation/filesystems/journalling.rst index 58ce6b395206..7e2be2faf653 100644 --- a/Documentation/filesystems/journalling.rst +++ b/Documentation/filesystems/journalling.rst @@ -10,27 +10,27 @@ Details The journalling layer is easy to use. You need to first of all create a journal_t data structure. There are two calls to do this dependent on how you decide to allocate the physical media on which the journal -resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in -filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used +resides. The jbd2_journal_init_inode() call is for journals stored in +filesystem inodes, or the jbd2_journal_init_dev() call can be used for journal stored on a raw device (in a continuous range of blocks). A journal_t is a typedef for a struct pointer, so when you are finally -finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up +finished make sure you call jbd2_journal_destroy() on it to free up any used kernel memory. Once you have got your journal_t object you need to 'mount' or load the journal file. The journalling layer expects the space for the journal was already allocated and initialized properly by the userspace tools. -When loading the journal you must call :c:func:`jbd2_journal_load` to process +When loading the journal you must call jbd2_journal_load() to process journal contents. If the client file system detects the journal contents does not need to be processed (or even need not have valid contents), it -may call :c:func:`jbd2_journal_wipe` to clear the journal contents before -calling :c:func:`jbd2_journal_load`. +may call jbd2_journal_wipe() to clear the journal contents before +calling jbd2_journal_load(). Note that jbd2_journal_wipe(..,0) calls -:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding -transactions in the journal and similarly :c:func:`jbd2_journal_load` will -call :c:func:`jbd2_journal_recover` if necessary. I would advise reading -:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage. +jbd2_journal_skip_recovery() for you if it detects any outstanding +transactions in the journal and similarly jbd2_journal_load() will +call jbd2_journal_recover() if necessary. I would advise reading +ext4_load_journal() in fs/ext4/super.c for examples on this stage. Now you can go ahead and start modifying the underlying filesystem. Almost. @@ -39,57 +39,57 @@ You still need to actually journal your filesystem changes, this is done by wrapping them into transactions. Additionally you also need to wrap the modification of each of the buffers with calls to the journal layer, so it knows what the modifications you are actually making are. To do -this use :c:func:`jbd2_journal_start` which returns a transaction handle. +this use jbd2_journal_start() which returns a transaction handle. -:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`, +jbd2_journal_start() and its counterpart jbd2_journal_stop(), which indicates the end of a transaction are nestable calls, so you can reenter a transaction if necessary, but remember you must call -:c:func:`jbd2_journal_stop` the same number of times as -:c:func:`jbd2_journal_start` before the transaction is completed (or more +jbd2_journal_stop() the same number of times as +jbd2_journal_start() before the transaction is completed (or more accurately leaves the update phase). Ext4/VFS makes use of this feature to simplify handling of inode dirtying, quota support, etc. Inside each transaction you need to wrap the modifications to the individual buffers (blocks). Before you start to modify a buffer you -need to call :c:func:`jbd2_journal_get_create_access()` / -:c:func:`jbd2_journal_get_write_access()` / -:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the +need to call jbd2_journal_get_create_access() / +jbd2_journal_get_write_access() / +jbd2_journal_get_undo_access() as appropriate, this allows the journalling layer to copy the unmodified data if it needs to. After all the buffer may be part of a previously uncommitted transaction. At this point you are at last ready to modify a buffer, and once you are have done so you need to call -:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a +jbd2_journal_dirty_metadata(). Or if you've asked for access to a buffer you now know is now longer required to be pushed back on the -device you can call :c:func:`jbd2_journal_forget` in much the same way as you -might have used :c:func:`bforget` in the past. +device you can call jbd2_journal_forget() in much the same way as you +might have used bforget() in the past. -A :c:func:`jbd2_journal_flush` may be called at any time to commit and +A jbd2_journal_flush() may be called at any time to commit and checkpoint all your transactions. -Then at umount time , in your :c:func:`put_super` you can then call -:c:func:`jbd2_journal_destroy` to clean up your in-core journal object. +Then at umount time , in your put_super() you can then call +jbd2_journal_destroy() to clean up your in-core journal object. Unfortunately there a couple of ways the journal layer can cause a deadlock. The first thing to note is that each task can only have a single outstanding transaction at any one time, remember nothing commits -until the outermost :c:func:`jbd2_journal_stop`. This means you must complete +until the outermost jbd2_journal_stop(). This means you must complete the transaction at the end of each file/inode/address etc. operation you perform, so that the journalling system isn't re-entered on another journal. Since transactions can't be nested/batched across differing journals, and another filesystem other than yours (say ext4) may be modified in a later syscall. -The second case to bear in mind is that :c:func:`jbd2_journal_start` can block +The second case to bear in mind is that jbd2_journal_start() can block if there isn't enough space in the journal for your transaction (based on the passed nblocks param) - when it blocks it merely(!) needs to wait for transactions to complete and be committed from other tasks, so -essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid -deadlocks you must treat :c:func:`jbd2_journal_start` / -:c:func:`jbd2_journal_stop` as if they were semaphores and include them in +essentially we are waiting for jbd2_journal_stop(). So to avoid +deadlocks you must treat jbd2_journal_start() / +jbd2_journal_stop() as if they were semaphores and include them in your semaphore ordering rules to prevent -deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking -behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as -easily as on :c:func:`jbd2_journal_start`. +deadlocks. Note that jbd2_journal_extend() has similar blocking +behaviour to jbd2_journal_start() so you can deadlock here just as +easily as on jbd2_journal_start(). Try to reserve the right number of blocks the first time. ;-). This will be the maximum number of blocks you are going to touch in this @@ -116,8 +116,8 @@ called after each transaction commit. You can also use that need processing when the transaction commits. JBD2 also provides a way to block all transaction updates via -:c:func:`jbd2_journal_lock_updates()` / -:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a +jbd2_journal_lock_updates() / +jbd2_journal_unlock_updates(). Ext4 uses this when it wants a window with a clean and stable fs for a moment. E.g. :: diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 318605de83f3..64f94a18d97e 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -433,15 +433,15 @@ prototypes:: locking rules: -========== ============= ================= ========= +====================== ============= ================= ========= ops inode->i_lock blocked_lock_lock may block -========== ============= ================= ========= +====================== ============= ================= ========= lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no lm_breaker_owns_lease: no no no -========== ============= ================= ========= +====================== ============= ================= ========= buffer_head =========== @@ -467,7 +467,6 @@ prototypes:: int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); - int (*media_changed) (struct gendisk *); void (*unlock_native_capacity) (struct gendisk *); int (*revalidate_disk) (struct gendisk *); int (*getgeo)(struct block_device *, struct hd_geometry *); @@ -483,14 +482,13 @@ release: yes ioctl: no compat_ioctl: no direct_access: no -media_changed: no unlock_native_capacity: no revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) ======================= =================== -media_changed, unlock_native_capacity and revalidate_disk are called only from +unlock_native_capacity and revalidate_disk are called only from check_disk_change(). swap_slot_free_notify is called with swap_lock and sometimes the page lock @@ -616,9 +614,9 @@ prototypes:: locking rules: -============= ======== =========================== +============= ========= =========================== ops mmap_lock PageLocked(page) -============= ======== =========================== +============= ========= =========================== open: yes close: yes fault: yes can return with page locked @@ -626,7 +624,7 @@ map_pages: yes page_mkwrite: yes can return with page locked pfn_mkwrite: yes access: yes -============= ======== =========================== +============= ========= =========================== ->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst index dea22d64f060..29c169c68961 100644 --- a/Documentation/filesystems/mount_api.rst +++ b/Documentation/filesystems/mount_api.rst @@ -213,7 +213,7 @@ The filesystem context points to a table of operations:: void (*free)(struct fs_context *fc); int (*dup)(struct fs_context *fc, struct fs_context *src_fc); int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); int (*parse_monolithic)(struct fs_context *fc, void *data); int (*get_tree)(struct fs_context *fc); int (*reconfigure)(struct fs_context *fc); @@ -247,7 +247,7 @@ manage the filesystem context. They are as follows: * :: int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); Called when a parameter is being added to the filesystem context. param points to the key name and maybe a value object. VFS-specific options diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst index 812754576845..abed4a2b1b82 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.rst +++ b/Documentation/filesystems/nfs/rpc-server-gss.rst @@ -10,12 +10,12 @@ purposes of authentication.) RPCGSS is specified in a few IETF documents: - - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt - - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt + - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt + - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt and there is a 3rd version being proposed: - - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt + - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt (At draft n. 02 at the time of writing) Background diff --git a/Documentation/filesystems/ocfs2.rst b/Documentation/filesystems/ocfs2.rst index 412386bc6506..42ca9a3d4c6e 100644 --- a/Documentation/filesystems/ocfs2.rst +++ b/Documentation/filesystems/ocfs2.rst @@ -14,7 +14,7 @@ get "mount.ocfs2" and "ocfs2_hb_ctl". Project web page: http://ocfs2.wiki.kernel.org Tools git tree: https://github.com/markfasheh/ocfs2-tools -OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ +OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/ All code copyright 2005 Oracle except when otherwise noted. diff --git a/Documentation/filesystems/omfs.rst b/Documentation/filesystems/omfs.rst index 4c8bb3074169..a104c25b7a2f 100644 --- a/Documentation/filesystems/omfs.rst +++ b/Documentation/filesystems/omfs.rst @@ -24,7 +24,7 @@ More information is available at: Various utilities, including mkomfs and omfsck, are included with omfsprogs, available at: - http://bobcopeland.com/karma/ + https://bobcopeland.com/karma/ Instructions are included in its README. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 660dbaf0b9b8..8ea83a51c266 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -328,7 +328,7 @@ the time of copy (on-demand vs. up-front). Multiple lower layers --------------------- -Multiple lower layers can now be given using the the colon (":") as a +Multiple lower layers can now be given using the colon (":") as a separator character between the directory names. For example: mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged @@ -560,8 +560,8 @@ When the NFS export feature is enabled, all directory index entries are verified on mount time to check that upper file handles are not stale. This verification may cause significant overhead in some cases. -Note: the mount options index=off,nfs_export=on are conflicting and will -result in an error. +Note: the mount options index=off,nfs_export=on are conflicting for a +read-write mount and will result in an error. Testsuite diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst index f46b05e9b96c..c482e1619e77 100644 --- a/Documentation/filesystems/path-lookup.rst +++ b/Documentation/filesystems/path-lookup.rst @@ -43,15 +43,15 @@ characters, and "components" that are sequences of one or more non-"``/``" characters. These form two kinds of paths. Those that start with slashes are "absolute" and start from the filesystem root. The others are "relative" and start from the current directory, or -from some other location specified by a file descriptor given to a -"``XXXat``" system call such as `openat() <openat_>`_. +from some other location specified by a file descriptor given to +"``*at()``" system calls such as `openat() <openat_>`_. .. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html It is tempting to describe the second kind as starting with a component, but that isn't always accurate: a pathname can lack both slashes and components, it can be empty, in other words. This is -generally forbidden in POSIX, but some of those "xxx``at``" system calls +generally forbidden in POSIX, but some of those "``*at()``" system calls in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For example, if you have an open file descriptor on an executable file you can execute it by calling `execveat() <execveat_>`_ passing @@ -69,17 +69,17 @@ pathname that is just slashes have a final component. If it does exist, it could be "``.``" or "``..``" which are handled quite differently from other components. -.. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 +.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 If a pathname ends with a slash, such as "``/tmp/foo/``" it might be tempting to consider that to have an empty final component. In many ways that would lead to correct results, but not always. In particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named by the final component, and they are required to work with pathnames -ending in "``/``". According to POSIX_ +ending in "``/``". According to POSIX_: - A pathname that contains at least one non- <slash> character and - that ends with one or more trailing <slash> characters shall not + A pathname that contains at least one non-<slash> character and + that ends with one or more trailing <slash> characters shall not be resolved successfully unless the last pathname component before the trailing <slash> characters names an existing directory or a directory entry that is to be created for a directory immediately @@ -229,7 +229,7 @@ happened to be looking at a dentry that was moved in this way, it might end up continuing the search down the wrong chain, and so miss out on part of the correct chain. -The name-lookup process (``d_lookup()``) does _not_ try to prevent this +The name-lookup process (``d_lookup()``) does *not* try to prevent this from happening, but only to detect when it happens. ``rename_lock`` is a seqlock that is updated whenever any dentry is renamed. If ``d_lookup`` finds that a rename happened while it @@ -376,7 +376,7 @@ table, and the mount point hash table. Bringing it together with ``struct nameidata`` ---------------------------------------------- -.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s +.. _First edition Unix: https://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s Throughout the process of walking a path, the current status is stored in a ``struct nameidata``, "namei" being the traditional name - dating @@ -398,7 +398,7 @@ held. ``struct qstr last`` ~~~~~~~~~~~~~~~~~~~~ -This is a string together with a length (i.e. _not_ ``nul`` terminated) +This is a string together with a length (i.e. *not* ``nul`` terminated) that is the "next" component in the pathname. ``int last_type`` @@ -655,8 +655,8 @@ This pattern of "try RCU-walk, if that fails try REF-walk" can be clearly seen in functions like ``filename_lookup()``, ``filename_parentat()``, ``filename_mountpoint()``, ``do_filp_open()``, and ``do_file_open_root()``. These five -correspond roughly to the four ``path_``* functions we met earlier, -each of which calls ``link_path_walk()``. The ``path_*`` functions are +correspond roughly to the four ``path_*()`` functions we met earlier, +each of which calls ``link_path_walk()``. The ``path_*()`` functions are called using different mode flags until a mode is found which works. They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If that fails with the error ``ECHILD`` they are called again with no @@ -720,7 +720,7 @@ against a dentry. The length and name pointer are copied into local variables, then ``read_seqcount_retry()`` is called to confirm the two are consistent, and only then is ``->d_compare()`` called. When standard filename comparison is used, ``dentry_cmp()`` is called -instead. Notably it does _not_ use ``read_seqcount_retry()``, but +instead. Notably it does *not* use ``read_seqcount_retry()``, but instead has a large comment explaining why the consistency guarantee isn't necessary. A subsequent ``read_seqcount_retry()`` will be sufficient to catch any problem that could occur at this point. @@ -928,7 +928,7 @@ if anything goes wrong it is much safer to just abort and try a more sedate approach. The emphasis here is "try quickly and check". It should probably be -"try quickly _and carefully,_ then check". The fact that checking is +"try quickly *and carefully*, then check". The fact that checking is needed is a reminder that the system is dynamic and only a limited number of things are safe at all. The most likely cause of errors in this whole process is assuming something is safe when in reality it @@ -1265,7 +1265,7 @@ Symlinks are different it seems. Both reading a symlink (with ``readlink()``) and looking up a symlink on the way to some other destination can update the atime on that symlink. -.. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 +.. _clearest statement: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 It is not clear why this is the case; POSIX has little to say on the subject. The `clearest statement`_ is that, if a particular implementation @@ -1365,7 +1365,7 @@ as well as blocking ".." if it would jump outside the starting point. resolution of "..". Magic-links are also blocked. ``LOOKUP_IN_ROOT`` resolves all path components as though the starting point -were the filesystem root. ``nd_jump_root()`` brings the resolution back to to +were the filesystem root. ``nd_jump_root()`` brings the resolution back to the starting point, and ".." at the starting point will act as a no-op. As with ``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect attacks against ".." resolution. Magic-links are also blocked. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 996f3cfe7030..533c79e8d2cd 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -123,10 +123,10 @@ show you how you can use /proc/sys to change settings. The directory /proc contains (among other things) one subdirectory for each process running on the system, which is named after the process ID (PID). -The link self points to the process reading the file system. Each process +The link 'self' points to the process reading the file system. Each process subdirectory has the entries listed in Table 1-1. -Note that an open a file descriptor to /proc/<pid> or to any of its +Note that an open file descriptor to /proc/<pid> or to any of its contained files or subdirectories does not prevent <pid> being reused for some other process in the event that <pid> exits. Operations on open /proc/<pid> file descriptors corresponding to dead processes @@ -220,7 +220,7 @@ file /proc/PID/status. It fields are described in table 1-2. The statm file contains more detailed information about the process memory usage. Its seven fields are explained in Table 1-3. The stat file -contains details information about the process itself. Its fields are +contains detailed information about the process itself. Its fields are explained in Table 1-4. (for SMP CONFIG users) @@ -545,7 +545,7 @@ encoded manner. The codes are the following: hg huge page advise flag nh no huge page advise flag mg mergable advise flag - bt - arm64 BTI guarded page + bt arm64 BTI guarded page == ======================================= Note that there is no guarantee that every flag and associated mnemonic will @@ -782,7 +782,7 @@ SPU For this case the APIC will generate the interrupt with a IRQ vector of 0xff. This might also be generated by chipset bugs. -RES, CAL, TLB] +RES, CAL, TLB rescheduling, call and TLB flush interrupts are sent from one CPU to another per the needs of the OS. Typically, their statistics are used by kernel developers and interested users to @@ -794,7 +794,7 @@ suppressed when the system is a uniprocessor. As of this writing, only i386 and x86_64 platforms support the new IRQ vector displays. Of some interest is the introduction of the /proc/irq directory to 2.4. -It could be used to set IRQ to CPU affinity, this means that you can "hook" an +It could be used to set IRQ to CPU affinity. This means that you can "hook" an IRQ to only one CPU, or to exclude a CPU of handling IRQs. The contents of the irq subdir is one subdir for each IRQ, and two files; default_smp_affinity and prof_cpu_mask. @@ -808,7 +808,7 @@ For example:: smp_affinity smp_affinity is a bitmask, in which you can specify which CPUs can handle the -IRQ, you can set it by doing:: +IRQ. You can set it by doing:: > echo 1 > /proc/irq/10/smp_affinity @@ -821,7 +821,7 @@ The contents of each smp_affinity file is the same by default:: ffffffff There is an alternate interface, smp_affinity_list which allows specifying -a cpu range instead of a bitmask:: +a CPU range instead of a bitmask:: > cat /proc/irq/0/smp_affinity_list 1024-1031 @@ -835,7 +835,7 @@ reports itself as being attached. This hardware locality information does not include information about any possible driver locality preference. prof_cpu_mask specifies which CPUs are to be profiled by the system wide -profiler. Default value is ffffffff (all cpus if there are only 32 of them). +profiler. Default value is ffffffff (all CPUs if there are only 32 of them). The way IRQs are routed is handled by the IO-APIC, and it's Round Robin between all the CPUs which are allowed to handle it. As usual the kernel has @@ -897,7 +897,7 @@ pagetypeinfo:: Fragmentation avoidance in the kernel works by grouping pages of different migrate types into the same contiguous regions of memory called page blocks. -A page block is typically the size of the default hugepage size e.g. 2MB on +A page block is typically the size of the default hugepage size, e.g. 2MB on X86-64. By keeping pages grouped based on their ability to move, the kernel can reclaim pages within a page block to satisfy a high-order allocation. @@ -965,7 +965,7 @@ varies by architecture and compile options. The following is from a ShmemPmdMapped: 0 kB MemTotal - Total usable ram (i.e. physical ram minus a few reserved + Total usable RAM (i.e. physical RAM minus a few reserved bits and the kernel binary code) MemFree The sum of LowFree+HighFree @@ -996,7 +996,7 @@ Inactive Memory which has been less recently used. It is more eligible to be reclaimed for other purposes HighTotal, HighFree - Highmem is all memory above ~860MB of physical memory + Highmem is all memory above ~860MB of physical memory. Highmem areas are for use by userspace programs, or for the pagecache. The kernel must use tricks to access this memory, making it slower to access than lowmem. @@ -1078,7 +1078,7 @@ Committed_AS using 1G. This 1G is memory which has been "committed" to by the VM and can be used at any time by the allocating application. With strict overcommit enabled on the system - (mode 2 in 'vm.overcommit_memory'),allocations which would + (mode 2 in 'vm.overcommit_memory'), allocations which would exceed the CommitLimit (detailed above) will not be permitted. This is useful if one needs to guarantee that processes will not fail due to lack of memory once that memory has been @@ -1099,7 +1099,7 @@ vmallocinfo Provides information about vmalloced/vmaped areas. One line per area, containing the virtual address range of the area, size in bytes, caller information of the creator, and optional information depending -on the kind of area : +on the kind of area: ========== =================================================== pages=nr number of pages @@ -1144,21 +1144,21 @@ on the kind of area : softirqs ~~~~~~~~ -Provides counts of softirq handlers serviced since boot time, for each cpu. +Provides counts of softirq handlers serviced since boot time, for each CPU. :: > cat /proc/softirqs - CPU0 CPU1 CPU2 CPU3 + CPU0 CPU1 CPU2 CPU3 HI: 0 0 0 0 - TIMER: 27166 27120 27097 27034 + TIMER: 27166 27120 27097 27034 NET_TX: 0 0 0 17 NET_RX: 42 0 0 39 - BLOCK: 0 0 107 1121 - TASKLET: 0 0 0 290 - SCHED: 27035 26983 26971 26746 - HRTIMER: 0 0 0 0 - RCU: 1678 1769 2178 2250 + BLOCK: 0 0 107 1121 + TASKLET: 0 0 0 290 + SCHED: 27035 26983 26971 26746 + HRTIMER: 0 0 0 0 + RCU: 1678 1769 2178 2250 1.3 IDE devices in /proc/ide @@ -1169,7 +1169,7 @@ the kernel is aware. There is one subdirectory for each IDE controller, the file drivers and a link for each IDE device, pointing to the device directory in the controller specific subtree. -The file drivers contains general information about the drivers used for the +The file 'drivers' contains general information about the drivers used for the IDE devices:: > cat /proc/ide/drivers @@ -1409,7 +1409,7 @@ These directories contain the four files shown in Table 1-10. ------------------------- Information about the available and actually used tty's can be found in the -directory /proc/tty.You'll find entries for drivers and line disciplines in +directory /proc/tty. You'll find entries for drivers and line disciplines in this directory, as shown in Table 1-11. @@ -1471,9 +1471,9 @@ second). The meanings of the columns are as follows, from left to right: - iowait: In a word, iowait stands for waiting for I/O to complete. But there are several problems: - 1. Cpu will not wait for I/O to complete, iowait is the time that a task is - waiting for I/O to complete. When cpu goes into idle state for - outstanding task io, another task will be scheduled on this CPU. + 1. CPU will not wait for I/O to complete, iowait is the time that a task is + waiting for I/O to complete. When CPU goes into idle state for + outstanding task I/O, another task will be scheduled on this CPU. 2. In a multi-core CPU, the task waiting for I/O to complete is not running on any CPU, so the iowait of each CPU is difficult to calculate. 3. The value of iowait field in /proc/stat will decrease in certain @@ -1529,8 +1529,8 @@ in Table 1-12, below. mb_groups details of multiblock allocator buddy cache of free blocks ============== ========================================================== -2.0 /proc/consoles ------------------- +1.10 /proc/consoles +------------------- Shows registered system console lines. To see which character device lines are currently used for the system console @@ -1590,10 +1590,9 @@ production system. Set up a development machine and test to make sure that everything works the way you want it to. You may have no alternative but to reboot the machine once an error has been made. -To change a value, simply echo the new value into the file. An example is -given below in the section on the file system data. You need to be root to do -this. You can create your own boot script to perform this every time your -system boots. +To change a value, simply echo the new value into the file. +You need to be root to do this. You can create your own boot script +to perform this every time your system boots. The files in /proc/sys can be used to fine tune and monitor miscellaneous and general things in the operation of the Linux kernel. Since some of the files @@ -1624,8 +1623,8 @@ Chapter 3: Per-process Parameters 3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score -------------------------------------------------------------------------------- -These file can be used to adjust the badness heuristic used to select which -process gets killed in out of memory conditions. +These files can be used to adjust the badness heuristic used to select which +process gets killed in out of memory (oom) conditions. The badness heuristic assigns a value to each candidate task ranging from 0 (never kill) to 1000 (always kill) to determine which process is targeted. The @@ -1634,9 +1633,6 @@ may allocate from based on an estimation of its current memory and swap use. For example, if a task is using all allowed memory, its badness score will be 1000. If it is using half of its allowed memory, its score will be 500. -There is an additional factor included in the badness score: the current memory -and swap usage is discounted by 3% for root processes. - The amount of "allowed" memory depends on the context in which the oom killer was called. If it is due to the memory assigned to the allocating task's cpuset being exhausted, the allowed memory represents the set of mems assigned to that @@ -1672,24 +1668,22 @@ The value of /proc/<pid>/oom_score_adj may be reduced no lower than the last value set by a CAP_SYS_RESOURCE process. To reduce the value any lower requires CAP_SYS_RESOURCE. -Caveat: when a parent task is selected, the oom killer will sacrifice any first -generation children with separate address spaces instead, if possible. This -avoids servers and important system daemons from being killed and loses the -minimal amount of work. - 3.2 /proc/<pid>/oom_score - Display current oom-killer score ------------------------------------------------------------- -This file can be used to check the current score used by the oom-killer is for +This file can be used to check the current score used by the oom-killer for any given <pid>. Use it together with /proc/<pid>/oom_score_adj to tune which process should be killed in an out-of-memory situation. +Please note that the exported value includes oom_score_adj so it is +effectively in range [0,2000]. + 3.3 /proc/<pid>/io - Display the IO accounting fields ------------------------------------------------------- -This file contains IO statistics for each running process +This file contains IO statistics for each running process. Example ~~~~~~~ @@ -1720,7 +1714,7 @@ The number of bytes which this task has caused to be read from storage. This is simply the sum of bytes which this process passed to read() and pread(). It includes things like tty IO and it is unaffected by whether or not actual physical disk IO was required (the read might have been satisfied from -pagecache) +pagecache). wchar @@ -1878,7 +1872,7 @@ For more information on mount propagation see: 3.6 /proc/<pid>/comm & /proc/<pid>/task/<tid>/comm -------------------------------------------------------- -These files provide a method to access a tasks comm value. It also allows for +These files provide a method to access a task's comm value. It also allows for a task to set its own or one of its thread siblings comm value. The comm value is limited in size compared to the cmdline value, so writing anything longer then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated @@ -1891,21 +1885,21 @@ This file provides a fast way to retrieve first level children pids of a task pointed by <pid>/<tid> pair. The format is a space separated stream of pids. -Note the "first level" here -- if a child has own children they will -not be listed here, one needs to read /proc/<children-pid>/task/<tid>/children +Note the "first level" here -- if a child has its own children they will +not be listed here; one needs to read /proc/<children-pid>/task/<tid>/children to obtain the descendants. Since this interface is intended to be fast and cheap it doesn't guarantee to provide precise results and some children might be skipped, especially if they've exited right after we printed their -pids, so one need to either stop or freeze processes being inspected +pids, so one needs to either stop or freeze processes being inspected if precise results are needed. 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file --------------------------------------------------------------- This file provides information associated with an opened file. The regular -files have at least three fields -- 'pos', 'flags' and mnt_id. The 'pos' +files have at least three fields -- 'pos', 'flags' and 'mnt_id'. The 'pos' represents the current offset of the opened file in decimal form [see lseek(2) for details], 'flags' denotes the octal O_xxx mask the file has been created with [see open(2) for details] and 'mnt_id' represents mount ID of @@ -1976,7 +1970,7 @@ For inotify files the format is the following:: flags: 02000000 inotify wd:3 ino:9e7e sdev:800013 mask:800afce ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:7e9e0000640d1b6d -where 'wd' is a watch descriptor in decimal form, ie a target file +where 'wd' is a watch descriptor in decimal form, i.e. a target file descriptor number, 'ino' and 'sdev' are inode and device where the target file resides and the 'mask' is the mask of events, all in hex form [see inotify(7) for more details]. @@ -2003,10 +1997,10 @@ For fanotify files the format is:: where fanotify 'flags' and 'event-flags' are values used in fanotify_init call, 'mnt_id' is the mount point identifier, 'mflags' is the value of flags associated with mark which are tracked separately from events -mask. 'ino', 'sdev' are target inode and device, 'mask' is the events +mask. 'ino' and 'sdev' are target inode and device, 'mask' is the events mask and 'ignored_mask' is the mask of events which are to be ignored. -All in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' -does provide information about flags and mask used in fanotify_mark +All are in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' +provide information about flags and mask used in fanotify_mark call [see fsnotify manpage for details]. While the first three lines are mandatory and always printed, the rest is @@ -2029,7 +2023,7 @@ Timerfd files where 'clockid' is the clock type and 'ticks' is the number of the timer expirations that have occurred [see timerfd_create(2) for details]. 'settime flags' are flags in octal form been used to setup the timer [see timerfd_settime(2) for -details]. 'it_value' is remaining time until the timer exiration. +details]. 'it_value' is remaining time until the timer expiration. 'it_interval' is the interval for the timer. Note the timer might be set up with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value' still exhibits timer's remaining time. @@ -2059,13 +2053,13 @@ are actually shared. 3.10 /proc/<pid>/timerslack_ns - Task timerslack value --------------------------------------------------------- This file provides the value of the task's timerslack value in nanoseconds. -This value specifies a amount of time that normal timers may be deferred +This value specifies an amount of time that normal timers may be deferred in order to coalesce timers and avoid unnecessary wakeups. -This allows a task's interactivity vs power consumption trade off to be +This allows a task's interactivity vs power consumption tradeoff to be adjusted. -Writing 0 to the file will set the tasks timerslack to the default value. +Writing 0 to the file will set the task's timerslack to the default value. Valid values are from 0 - ULLONG_MAX @@ -2105,10 +2099,10 @@ Example Description ~~~~~~~~~~~ -x86 specific entries: +x86 specific entries ~~~~~~~~~~~~~~~~~~~~~ -AVX512_elapsed_ms: +AVX512_elapsed_ms ^^^^^^^^^^^^^^^^^^ If AVX512 is supported on the machine, this entry shows the milliseconds @@ -2134,8 +2128,8 @@ AVX512_elapsed_ms: the task is unlikely an AVX512 user, but depends on the workload and the scheduling scenario, it also could be a false negative mentioned above. -Configuring procfs ------------------- +Chapter 4: Configuring procfs +============================= 4.1 Mount options --------------------- @@ -2178,47 +2172,45 @@ information about processes information, just add identd to this group. subset=pid hides all top level files and directories in the procfs that are not related to tasks. -5 Filesystem behavior ----------------------------- +Chapter 5: Filesystem behavior +============================== Originally, before the advent of pid namepsace, procfs was a global file system. It means that there was only one procfs instance in the system. When pid namespace was added, a separate procfs instance was mounted in each pid namespace. So, procfs mount options are global among all -mountpoints within the same namespace. - -:: +mountpoints within the same namespace:: -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 -# strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc -mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 -+++ exited with 0 +++ + # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc + mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 + +++ exited with 0 +++ -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 -proc /tmp/proc proc rw,relatime,hidepid=2 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 + proc /tmp/proc proc rw,relatime,hidepid=2 0 0 and only after remounting procfs mount options will change at all -mountpoints. +mountpoints:: -# mount -o remount,hidepid=1 -t proc proc /tmp/proc + # mount -o remount,hidepid=1 -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=1 0 0 -proc /tmp/proc proc rw,relatime,hidepid=1 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=1 0 0 + proc /tmp/proc proc rw,relatime,hidepid=1 0 0 This behavior is different from the behavior of other filesystems. The new procfs behavior is more like other filesystems. Each procfs mount creates a new procfs instance. Mount options affect own procfs instance. It means that it became possible to have several procfs instances -displaying tasks with different filtering options in one pid namespace. +displaying tasks with different filtering options in one pid namespace:: -# mount -o hidepid=invisible -t proc proc /proc -# mount -o hidepid=noaccess -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=invisible 0 0 -proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 + # mount -o hidepid=invisible -t proc proc /proc + # mount -o hidepid=noaccess -t proc proc /tmp/proc + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=invisible 0 0 + proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 diff --git a/Documentation/filesystems/quota.rst b/Documentation/filesystems/quota.rst index a30cdd47c652..abd4303c546e 100644 --- a/Documentation/filesystems/quota.rst +++ b/Documentation/filesystems/quota.rst @@ -18,7 +18,7 @@ Quota limits (and amount of grace time) are set independently for each filesystem. For more details about quota design, see the documentation in quota-tools package -(http://sourceforge.net/projects/linuxquota). +(https://sourceforge.net/projects/linuxquota). Quota netlink interface ======================= @@ -31,11 +31,11 @@ the above events to userspace. There they can be captured by an application and processed accordingly. The interface uses generic netlink framework (see -http://lwn.net/Articles/208755/ and http://people.suug.ch/~tgr/libnl/ for more -details about this layer). The name of the quota generic netlink interface -is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. -Since the quota netlink protocol is not namespace aware, quota netlink messages -are sent only in initial network namespace. +https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for +more details about this layer). The name of the quota generic netlink interface +is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. Since +the quota netlink protocol is not namespace aware, quota netlink messages are +sent only in initial network namespace. Currently, the interface supports only one message type QUOTA_NL_C_WARNING. This command is used to send a notification about any of the above mentioned diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.rst b/Documentation/filesystems/ramfs-rootfs-initramfs.rst index 3fddacc6bf14..4598b0d90b60 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.rst +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.rst @@ -246,15 +246,15 @@ If you don't already understand what shared libraries, devices, and paths you need to get a minimal root filesystem up and running, here are some references: -- http://www.tldp.org/HOWTO/Bootdisk-HOWTO/ -- http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html +- https://www.tldp.org/HOWTO/Bootdisk-HOWTO/ +- https://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html - http://www.linuxfromscratch.org/lfs/view/stable/ -The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is +The "klibc" package (https://www.kernel.org/pub/linux/libs/klibc) is designed to be a tiny C library to statically link early userspace code against, along with some related utilities. It is BSD licensed. -I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net) +I use uClibc (https://www.uclibc.org) and busybox (https://www.busybox.net) myself. These are LGPL and GPL, respectively. (A self-contained initramfs package is planned for the busybox 1.3 release.) diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst index a265f3e2cc80..742fbd21dc1f 100644 --- a/Documentation/filesystems/sysfs-pci.rst +++ b/Documentation/filesystems/sysfs-pci.rst @@ -63,7 +63,7 @@ files, each with their own function. binary - file contains binary data cpumask - file contains a cpumask type -.. [1] rw for RESOURCE_IO (I/O port) regions only +.. [1] rw for IORESOURCE_IO (I/O port) regions only The read only files are informational, writes to them will be ignored, with the exception of the 'rom' file. Writable files can be used to perform diff --git a/Documentation/filesystems/sysfs-tagging.rst b/Documentation/filesystems/sysfs-tagging.rst index 8888a05c398e..83647e10c207 100644 --- a/Documentation/filesystems/sysfs-tagging.rst +++ b/Documentation/filesystems/sysfs-tagging.rst @@ -15,7 +15,7 @@ To avoid that problem and allow existing applications in network namespaces to see the same interface that is currently presented in sysfs, sysfs now has tagging directory support. -By using the network namespace pointers as tags to separate out the +By using the network namespace pointers as tags to separate out the sysfs directory entries we ensure that we don't have conflicts in the directories and applications only see a limited set of the network devices. diff --git a/Documentation/filesystems/tmpfs.rst b/Documentation/filesystems/tmpfs.rst index 4e95929301a5..c44f8b1d3cab 100644 --- a/Documentation/filesystems/tmpfs.rst +++ b/Documentation/filesystems/tmpfs.rst @@ -150,6 +150,22 @@ These options do not have any effect on remount. You can change these parameters with chmod(1), chown(1) and chgrp(1) on a mounted filesystem. +tmpfs has a mount option to select whether it will wrap at 32- or 64-bit inode +numbers: + +======= ======================== +inode64 Use 64-bit inode numbers +inode32 Use 32-bit inode numbers +======= ======================== + +On a 32-bit kernel, inode32 is implicit, and inode64 is refused at mount time. +On a 64-bit kernel, CONFIG_TMPFS_INODE64 sets the default. inode64 avoids the +possibility of multiple files with the same inode number on a single device; +but risks glibc failing with EOVERFLOW once 33-bit inode numbers are reached - +if a long-lived tmpfs is accessed by 32-bit applications so ancient that +opening a file larger than 2GiB fails with EINVAL. + + So 'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs' will give you tmpfs instance on /mytmpfs which can allocate 10GB RAM/SWAP in 10240 inodes and it is only accessible by root. @@ -161,3 +177,5 @@ RAM/SWAP in 10240 inodes and it is only accessible by root. Hugh Dickins, 4 June 2007 :Updated: KOSAKI Motohiro, 16 Mar 2010 +:Updated: + Chris Down, 13 July 2020 diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst index 16efd729bf7c..1f39c8cea702 100644 --- a/Documentation/filesystems/ubifs-authentication.rst +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -433,9 +433,9 @@ will then have to be provided beforehand in the normal way. References ========== -[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html +[CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html -[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ +[DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ [DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst diff --git a/Documentation/filesystems/udf.rst b/Documentation/filesystems/udf.rst index d9badbf285b2..f9489ddbb767 100644 --- a/Documentation/filesystems/udf.rst +++ b/Documentation/filesystems/udf.rst @@ -72,4 +72,4 @@ For the latest version and toolset see: Documentation on UDF and ECMA 167 is available FREE from: - http://www.osta.org/ - - http://www.ecma-international.org/ + - https://www.ecma-international.org/ diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index ed17771c212b..ca52c82e5bb5 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -392,7 +392,7 @@ Extended attributes are name:value pairs. ``set`` Called by the VFS to set the value of a particular extended attribute. When the new value is NULL, called to remove a - particular extended attribute. This method is called by the the + particular extended attribute. This method is called by the setxattr(2) and removexattr(2) system calls. When none of the xattr handlers of a filesystem match the specified @@ -652,7 +652,7 @@ at any point after PG_Dirty is clear. Once it is known to be safe, PG_Writeback is cleared. Writeback makes use of a writeback_control structure to direct the -operations. This gives the the writepage and writepages operations some +operations. This gives the writepage and writepages operations some information about the nature of and reason for the writeback request, and the constraints under which it is being done. It is also used to return information back to the caller about the result of a writepage or @@ -766,9 +766,9 @@ cache in your filesystem. The following members are defined: ``writepages`` called by the VM to write out pages associated with the - address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then + address_space object. If wbc->sync_mode is WB_SYNC_ALL, then the writeback_control will specify a range of pages that must be - written out. If it is WBC_SYNC_NONE, then a nr_to_write is + written out. If it is WB_SYNC_NONE, then a nr_to_write is given and that many pages should be written if possible. If no ->writepages is given, then mpage_writepages is used instead. This will choose pages from the address space that are tagged as @@ -1116,7 +1116,7 @@ otherwise noted. before any bytes were remapped. The remap_flags parameter accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the implementation must only remap if the requested file ranges have - identical contents. If REMAP_CAN_SHORTEN is set, the caller is + identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is ok with the implementation shortening the request length to satisfy alignment or EOF requirements (or any other reason). @@ -1431,13 +1431,13 @@ Resources version.) Creating Linux virtual filesystems. 2002 - <http://lwn.net/Articles/13325/> + <https://lwn.net/Articles/13325/> The Linux Virtual File-system Layer by Neil Brown. 1999 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> A tour of the Linux VFS by Michael K. Johnson. 1996 - <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> + <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> A small trail through the Linux kernel by Andries Brouwer. 2001 - <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> + <https://www.win.tue.nl/~aeb/linux/vfs/trail.html> diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst index 71d845c6a700..6c18bc8ce332 100644 --- a/Documentation/filesystems/zonefs.rst +++ b/Documentation/filesystems/zonefs.rst @@ -110,14 +110,14 @@ contain files named "0", "1", "2", ... The file numbers also represent increasing zone start sector on the device. All read and write operations to zone files are not allowed beyond the file -maximum size, that is, beyond the zone size. Any access exceeding the zone -size is failed with the -EFBIG error. +maximum size, that is, beyond the zone capacity. Any access exceeding the zone +capacity is failed with the -EFBIG error. Creating, deleting, renaming or modifying any attribute of files and sub-directories is not allowed. The number of blocks of a file as reported by stat() and fstat() indicates the -size of the file zone, or in other words, the maximum file size. +capacity of the zone file, or in other words, the maximum file size. Conventional zone files ----------------------- @@ -156,8 +156,8 @@ all accepted. Truncating sequential zone files is allowed only down to 0, in which case, the zone is reset to rewind the file zone write pointer position to the start of -the zone, or up to the zone size, in which case the file's zone is transitioned -to the FULL state (finish zone operation). +the zone, or up to the zone capacity, in which case the file's zone is +transitioned to the FULL state (finish zone operation). Format options -------------- @@ -324,7 +324,7 @@ file size set to 0. This is necessary as the write pointer of read-only zones is defined as invalib by the ZBC and ZAC standards, making it impossible to discover the amount of data that has been written to the zone. In the case of a read-only zone discovered at run-time, as indicated in the previous section. -the size of the zone file is left unchanged from its last updated value. +The size of the zone file is left unchanged from its last updated value. Zonefs User Space Tools ======================= @@ -401,8 +401,9 @@ append-writes to the file:: # ls -l /mnt/seq/0 -rw-r----- 1 root root 0 Nov 25 13:49 /mnt/seq/0 -Since files are statically mapped to zones on the disk, the number of blocks of -a file as reported by stat() and fstat() indicates the size of the file zone:: +Since files are statically mapped to zones on the disk, the number of blocks +of a file as reported by stat() and fstat() indicates the capacity of the file +zone:: # stat /mnt/seq/0 File: /mnt/seq/0 @@ -416,5 +417,6 @@ a file as reported by stat() and fstat() indicates the size of the file zone:: The number of blocks of the file ("Blocks") in units of 512B blocks gives the maximum file size of 524288 * 512 B = 256 MB, corresponding to the device zone -size in this example. Of note is that the "IO block" field always indicates the -minimum I/O size for writes and corresponds to the device physical sector size. +capacity in this example. Of note is that the "IO block" field always +indicates the minimum I/O size for writes and corresponds to the device +physical sector size. |