diff options
author | Kari Argillander <kari.argillander@gmail.com> | 2021-08-03 14:57:09 +0300 |
---|---|---|
committer | Konstantin Komarov <almaz.alexandrovich@paragon-software.com> | 2021-08-30 18:39:14 +0300 |
commit | e8b8e97f91b80f08a2f1b7ea4f81e7af61b2cc2f (patch) | |
tree | dfa9cd09534c9d3f495a4bd5c36fd182856810be /fs/ntfs3/file.c | |
parent | b8155e95de38b25a69dfb03e4731fd6c5a28531e (diff) | |
download | linux-e8b8e97f91b80f08a2f1b7ea4f81e7af61b2cc2f.tar.xz |
fs/ntfs3: Restyle comments to better align with kernel-doc
Capitalize comments and end with period for better reading.
Also function comments are now little more kernel-doc style. This way we
can easily convert them to kernel-doc style if we want. Note that these
are not yet complete with this style. Example function comments start
with /* and in kernel-doc style they start /**.
Use imperative mood in function descriptions.
Change words like ntfs -> NTFS, linux -> Linux.
Use "we" not "I" when commenting code.
Signed-off-by: Kari Argillander <kari.argillander@gmail.com>
Signed-off-by: Konstantin Komarov <almaz.alexandrovich@paragon-software.com>
Diffstat (limited to 'fs/ntfs3/file.c')
-rw-r--r-- | fs/ntfs3/file.c | 96 |
1 files changed, 53 insertions, 43 deletions
diff --git a/fs/ntfs3/file.c b/fs/ntfs3/file.c index a959f6197c99..26346771d9dc 100644 --- a/fs/ntfs3/file.c +++ b/fs/ntfs3/file.c @@ -3,8 +3,10 @@ * * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved. * - * regular file handling primitives for ntfs-based filesystems + * Regular file handling primitives for NTFS-based filesystems. + * */ + #include <linux/backing-dev.h> #include <linux/buffer_head.h> #include <linux/compat.h> @@ -62,7 +64,7 @@ static long ntfs_ioctl(struct file *filp, u32 cmd, unsigned long arg) case FITRIM: return ntfs_ioctl_fitrim(sbi, arg); } - return -ENOTTY; /* Inappropriate ioctl for device */ + return -ENOTTY; /* Inappropriate ioctl for device. */ } #ifdef CONFIG_COMPAT @@ -74,7 +76,7 @@ static long ntfs_compat_ioctl(struct file *filp, u32 cmd, unsigned long arg) #endif /* - * inode_operations::getattr + * ntfs_getattr - inode_operations::getattr */ int ntfs_getattr(struct user_namespace *mnt_userns, const struct path *path, struct kstat *stat, u32 request_mask, u32 flags) @@ -170,7 +172,7 @@ static int ntfs_extend_initialized_size(struct file *file, zero_user_segment(page, zerofrom, PAGE_SIZE); - /* this function in any case puts page*/ + /* This function in any case puts page. */ err = pagecache_write_end(file, mapping, pos, len, len, page, fsdata); if (err < 0) @@ -195,9 +197,7 @@ out: } /* - * ntfs_zero_range - * - * Helper function for punch_hole. + * ntfs_zero_range - Helper function for punch_hole. * It zeroes a range [vbo, vbo_to) */ static int ntfs_zero_range(struct inode *inode, u64 vbo, u64 vbo_to) @@ -356,7 +356,7 @@ void ntfs_sparse_cluster(struct inode *inode, struct page *page0, CLST vcn, } /* - * file_operations::mmap + * ntfs_file_mmap - file_operations::mmap */ static int ntfs_file_mmap(struct file *file, struct vm_area_struct *vma) { @@ -387,7 +387,7 @@ static int ntfs_file_mmap(struct file *file, struct vm_area_struct *vma) from + vma->vm_end - vma->vm_start); if (is_sparsed(ni)) { - /* allocate clusters for rw map */ + /* Allocate clusters for rw map. */ struct ntfs_sb_info *sbi = inode->i_sb->s_fs_info; CLST lcn, len; CLST vcn = from >> sbi->cluster_bits; @@ -436,7 +436,7 @@ static int ntfs_extend(struct inode *inode, loff_t pos, size_t count, if (end <= inode->i_size && !extend_init) return 0; - /*mark rw ntfs as dirty. it will be cleared at umount*/ + /* Mark rw ntfs as dirty. It will be cleared at umount. */ ntfs_set_state(ni->mi.sbi, NTFS_DIRTY_DIRTY); if (end > inode->i_size) { @@ -530,6 +530,8 @@ static int ntfs_truncate(struct inode *inode, loff_t new_size) } /* + * ntfs_fallocate + * * Preallocate space for a file. This implements ntfs's fallocate file * operation, which gets called from sys_fallocate system call. User * space requests 'len' bytes at 'vbo'. If FALLOC_FL_KEEP_SIZE is set @@ -547,11 +549,11 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) loff_t i_size; int err; - /* No support for dir */ + /* No support for dir. */ if (!S_ISREG(inode->i_mode)) return -EOPNOTSUPP; - /* Return error if mode is not supported */ + /* Return error if mode is not supported. */ if (mode & ~(FALLOC_FL_KEEP_SIZE | FALLOC_FL_PUNCH_HOLE | FALLOC_FL_COLLAPSE_RANGE)) { ntfs_inode_warn(inode, "fallocate(0x%x) is not supported", @@ -565,7 +567,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) i_size = inode->i_size; if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) { - /* should never be here, see ntfs_file_open*/ + /* Should never be here, see ntfs_file_open. */ err = -EOPNOTSUPP; goto out; } @@ -646,7 +648,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) /* * Write data that will be shifted to preserve them - * when discarding page cache below + * when discarding page cache below. */ err = filemap_write_and_wait_range(inode->i_mapping, end, LLONG_MAX); @@ -663,7 +665,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) ni_unlock(ni); } else { /* - * normal file: allocate clusters, do not change 'valid' size + * Normal file: Allocate clusters, do not change 'valid' size. */ err = ntfs_set_size(inode, max(end, i_size)); if (err) @@ -677,10 +679,10 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) bool new; /* - * allocate but not zero new clusters (see below comments) - * this breaks security (one can read unused on-disk areas) - * zeroing these clusters may be too long - * may be we should check here for root rights? + * Allocate but do not zero new clusters. (see below comments) + * This breaks security: One can read unused on-disk areas. + * Zeroing these clusters may be too long. + * Maybe we should check here for root rights? */ for (; vcn < cend; vcn += clen) { err = attr_data_get_block(ni, vcn, cend - vcn, @@ -691,15 +693,15 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) continue; /* - * Unwritten area - * NTFS is not able to store several unwritten areas - * Activate 'ntfs_sparse_cluster' to zero new allocated clusters + * Unwritten area. + * NTFS is not able to store several unwritten areas. + * Activate 'ntfs_sparse_cluster' to zero new allocated clusters. * * Dangerous in case: * 1G of sparsed clusters + 1 cluster of data => * valid_size == 1G + 1 cluster * fallocate(1G) will zero 1G and this can be very long - * xfstest 016/086 will fail without 'ntfs_sparse_cluster' + * xfstest 016/086 will fail without 'ntfs_sparse_cluster'. */ ntfs_sparse_cluster(inode, NULL, vcn, min(vcn_v - vcn, clen)); @@ -708,7 +710,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len) if (mode & FALLOC_FL_KEEP_SIZE) { ni_lock(ni); - /*true - keep preallocated*/ + /* True - Keep preallocated. */ err = attr_set_size(ni, ATTR_DATA, NULL, 0, &ni->file.run, i_size, &ni->i_valid, true, NULL); @@ -730,7 +732,7 @@ out: } /* - * inode_operations::setattr + * ntfs3_setattr - inode_operations::setattr */ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry, struct iattr *attr) @@ -744,9 +746,9 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry, int err; if (sbi->options.no_acs_rules) { - /* "no access rules" - force any changes of time etc. */ + /* "No access rules" - Force any changes of time etc. */ attr->ia_valid |= ATTR_FORCE; - /* and disable for editing some attributes */ + /* and disable for editing some attributes. */ attr->ia_valid &= ~(ATTR_UID | ATTR_GID | ATTR_MODE); ia_valid = attr->ia_valid; } @@ -759,7 +761,7 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry, loff_t oldsize = inode->i_size; if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) { - /* should never be here, see ntfs_file_open*/ + /* Should never be here, see ntfs_file_open(). */ err = -EOPNOTSUPP; goto out; } @@ -783,7 +785,7 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry, if (err) goto out; - /* linux 'w' -> windows 'ro' */ + /* Linux 'w' -> Windows 'ro'. */ if (0222 & inode->i_mode) ni->std_fa &= ~FILE_ATTRIBUTE_READONLY; else @@ -834,7 +836,11 @@ static ssize_t ntfs_file_read_iter(struct kiocb *iocb, struct iov_iter *iter) return err; } -/* returns array of locked pages */ +/* + * ntfs_get_frame_pages + * + * Return: Array of locked pages. + */ static int ntfs_get_frame_pages(struct address_space *mapping, pgoff_t index, struct page **pages, u32 pages_per_frame, bool *frame_uptodate) @@ -867,7 +873,9 @@ static int ntfs_get_frame_pages(struct address_space *mapping, pgoff_t index, return 0; } -/*helper for ntfs_file_write_iter (compressed files)*/ +/* + * ntfs_compress_write - Helper for ntfs_file_write_iter() (compressed files). + */ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) { int err; @@ -913,7 +921,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) if (err) goto out; - /* zero range [valid : pos) */ + /* Zero range [valid : pos). */ while (valid < pos) { CLST lcn, clen; @@ -932,7 +940,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) continue; } - /* Load full frame */ + /* Load full frame. */ err = ntfs_get_frame_pages(mapping, frame_vbo >> PAGE_SHIFT, pages, pages_per_frame, &frame_uptodate); @@ -978,7 +986,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) ni->i_valid = valid = frame_vbo + frame_size; } - /* copy user data [pos : pos + count) */ + /* Copy user data [pos : pos + count). */ while (count) { size_t copied, bytes; @@ -996,7 +1004,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) goto out; } - /* Load full frame */ + /* Load full frame. */ err = ntfs_get_frame_pages(mapping, index, pages, pages_per_frame, &frame_uptodate); if (err) @@ -1025,7 +1033,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from) ip = off >> PAGE_SHIFT; off = offset_in_page(pos); - /* copy user data to pages */ + /* Copy user data to pages. */ for (;;) { size_t cp, tail = PAGE_SIZE - off; @@ -1091,7 +1099,7 @@ out: } /* - * file_operations::write_iter + * ntfs_file_write_iter - file_operations::write_iter */ static ssize_t ntfs_file_write_iter(struct kiocb *iocb, struct iov_iter *from) { @@ -1127,7 +1135,7 @@ static ssize_t ntfs_file_write_iter(struct kiocb *iocb, struct iov_iter *from) goto out; if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) { - /* should never be here, see ntfs_file_open*/ + /* Should never be here, see ntfs_file_open() */ ret = -EOPNOTSUPP; goto out; } @@ -1149,7 +1157,7 @@ out: } /* - * file_operations::open + * ntfs_file_open - file_operations::open */ int ntfs_file_open(struct inode *inode, struct file *file) { @@ -1160,7 +1168,7 @@ int ntfs_file_open(struct inode *inode, struct file *file) return -EOPNOTSUPP; } - /* Decompress "external compressed" file if opened for rw */ + /* Decompress "external compressed" file if opened for rw. */ if ((ni->ni_flags & NI_FLAG_COMPRESSED_MASK) && (file->f_flags & (O_WRONLY | O_RDWR | O_TRUNC))) { #ifdef CONFIG_NTFS3_LZX_XPRESS @@ -1180,7 +1188,7 @@ int ntfs_file_open(struct inode *inode, struct file *file) } /* - * file_operations::release + * ntfs_file_release - file_operations::release */ static int ntfs_file_release(struct inode *inode, struct file *file) { @@ -1188,7 +1196,7 @@ static int ntfs_file_release(struct inode *inode, struct file *file) struct ntfs_sb_info *sbi = ni->mi.sbi; int err = 0; - /* if we are the last writer on the inode, drop the block reservation */ + /* If we are last writer on the inode, drop the block reservation. */ if (sbi->options.prealloc && ((file->f_mode & FMODE_WRITE) && atomic_read(&inode->i_writecount) == 1)) { ni_lock(ni); @@ -1203,7 +1211,9 @@ static int ntfs_file_release(struct inode *inode, struct file *file) return err; } -/* file_operations::fiemap */ +/* + * ntfs_fiemap - file_operations::fiemap + */ int ntfs_fiemap(struct inode *inode, struct fiemap_extent_info *fieinfo, __u64 start, __u64 len) { |