statx.2, open.2: document STATX_DIOALIGN
Subsystems (5)
Eric Biggers
maintainerPATCH v3 1/1 statx.2, open.2: document STATX_DIOALIGN
From: Eric Biggers <[email protected]>
Document the STATX_DIOALIGN support for statx()
(https://git.kernel.org/linus/725737e7c21d2d25).
---
I'm resending this now that support for STATX_DIOALIGN has been merged upstream.
v3: updated mentions of Linux version, fixed some punctuation, and added
a Reviewed-by
v2: rebased onto man-pages master branch, mentioned xfs, and updated
link to patchset
man2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- man2/statx.2 | 29 +++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 11 deletions(-)
man2/open.2 +32 -11
@@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. -However there is currently no filesystem\-independent -interface for an application to discover these restrictions for a given -file or filesystem. -Some filesystems provide their own interfaces -for doing so, for example the +The handling of misaligned +.B O_DIRECT +I/Os also varies; they can either fail with +.B EINVAL +or fall back to buffered I/O. +.PP +Since Linux 6.1, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; see +.BR statx (2). +.PP +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, for example the .B XFS_IOC_DIOINFO operation in .BR xfsctl (3). +.B STATX_DIOALIGN +should be used instead when it is available. .PP -Under Linux 2.4, transfer sizes, the alignment of the user buffer, -and the file offset must all be multiples of the logical block size -of the filesystem. -Since Linux 2.6.0, alignment to the logical block size of the -underlying storage (typically 512 bytes) suffices. -The logical block size can be determined using the +If none of the above is available, then direct I/O support and alignment +restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:
man2/statx.2 +29 -0
@@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in
@@ -247,6 +252,8 @@ STATX_BTIME Want stx_btime STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. It is deprecated and should not be used. STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) .TE .in .PP
@@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align +and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).
base-commit: bc28d289e5066fc626df260bafc249846a0f6ae6
Signature · 1 line
2.37.3
Quoted 11 lines · Eric Biggers
From: Eric Biggers <[email protected]>
Document the
STATX_DIOALIGNsupport forstatx()
(https://git.kernel.org/linus/725737e7c21d2d25).Reviewed-by Darrick J. Wong <[email protected]>Signed-off-by Eric Biggers <[email protected]>---
I'm resending this now that support for
STATX_DIOALIGNhas been merged upstream.
Woo! Thank you for getting this over the line! :)
--D
Quoted 128 lines
v3: updated mentions of Linux version, fixed some punctuation, and added
a Reviewed-byv2: rebased onto man-pages master branch, mentioned xfs, and updated
link to patchsetman2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- man2/statx.2 | 29 +++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 11 deletions(-)man2/open.2 +32
-11@@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. -However there is currently no filesystem\-independent -interface for an application to discover these restrictions for a given -file or filesystem. -Some filesystems provide their own interfaces -for doing so, for example the +The handling of misaligned +.B O_DIRECT +I/Os also varies; they can either fail with +.B EINVAL +or fall back to buffered I/O. +.PP +Since Linux 6.1, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; see +.BR statx (2). +.PP +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, for example the .B XFS_IOC_DIOINFO operation in .BR xfsctl (3). +.B STATX_DIOALIGN +should be used instead when it is available. .PP -Under Linux 2.4, transfer sizes, the alignment of the user buffer, -and the file offset must all be multiples of the logical block size -of the filesystem. -Since Linux 2.6.0, alignment to the logical block size of the -underlying storage (typically 512 bytes) suffices. -The logical block size can be determined using the +If none of the above is available, then direct I/O support and alignment +restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:man2/statx.2 +29
-0@@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in@@ -247,6 +252,8 @@ STATX_BTIME Want stx_btime STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. It is deprecated and should not be used. STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) .TE .in .PP@@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align +and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).base-commit:
bc28d289e5066fc626df260bafc249846a0f6ae6Signature · 1 line
2.37.3
Hi Eric,
Quoted 7 lines · Eric Biggers
From: Eric Biggers <[email protected]>
Document the
STATX_DIOALIGNsupport forstatx()
(https://git.kernel.org/linus/725737e7c21d2d25).Reviewed-by Darrick J. Wong <[email protected]>Signed-off-by Eric Biggers <[email protected]>
Please see some formatting comments below.
Quoted 4 lines
---
I'm resending this now that support for
STATX_DIOALIGNhas been merged upstream.
Thanks.
Cheers,
Alex
Quoted 48 lines
v3: updated mentions of Linux version, fixed some punctuation, and added
a Reviewed-byv2: rebased onto man-pages master branch, mentioned xfs, and updated
link to patchsetman2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- man2/statx.2 | 29 +++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 11 deletions(-)man2/open.2 +21
-5@@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. -However there is currently no filesystem\-independent -interface for an application to discover these restrictions for a given -file or filesystem. -Some filesystems provide their own interfaces -for doing so, for example the +The handling of misaligned +.B O_DIRECT +I/Os also varies; they can either fail with +.B EINVAL +or fall back to buffered I/O. +.PP +Since Linux 6.1, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; see +.BR statx (2). +.PP +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, for example the .B XFS_IOC_DIOINFO operation in .BR xfsctl (3).
man2/open.2 of user-space buffers and the file offset of I/Os. · line 1762
Quoted 10 lines
man2/open.2 +3
-6+.B STATX_DIOALIGN +should be used instead when it is available. .PP -Under Linux 2.4, transfer sizes, the alignment of the user buffer, -and the file offset must all be multiples of the logical block size -of the filesystem. -Since Linux 2.6.0, alignment to the logical block size of the -underlying storage (typically 512 bytes) suffices. -The logical block size can be determined using the +If none of the above is available, then direct I/O support and alignment
Please use semantic newlines.
See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase bound‐ aries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases.
Quoted 38 lines
man2/open.2 +8
-0+restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:man2/statx.2 +7
-0@@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in@@ -247,6 +252,8 @@ STATX_BTIME Want stx_btime STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. It is deprecated and should not be used. STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) .TE .in .PP
man2/statx.2 This is the same number reported by · line 420
Quoted 7 lines
man2/statx.2 +4
-0@@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT )
.RB and remove the "".
man2/statx.2 This is the same number reported by · line 424
Quoted 4 lines
man2/statx.2 +4
-0+on this file, or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align
.RI
Quoted 19 lines
man2/statx.2 +14
-0+and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).base-commit:
bc28d289e5066fc626df260bafc249846a0f6ae6
Signature · 1 line
<http://www.alejandro-colomar.es/>
Quoted 72 lines · Alejandro Colomar
Hi Eric,
Quoted 7 lines · Eric Biggers
From: Eric Biggers <[email protected]>
Document the
STATX_DIOALIGNsupport forstatx()
(https://git.kernel.org/linus/725737e7c21d2d25).Reviewed-by Darrick J. Wong <[email protected]>Signed-off-by Eric Biggers <[email protected]>Please see some formatting comments below.
Quoted 4 lines
---
I'm resending this now that support for
STATX_DIOALIGNhas been merged upstream.Thanks.
Cheers,
AlexQuoted 49 lines
v3: updated mentions of Linux version, fixed some punctuation, and added
a Reviewed-byv2: rebased onto man-pages master branch, mentioned xfs, and updated
link to patchsetman2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- man2/statx.2 | 29 +++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 11 deletions(-)man2/open.2 +22
-5@@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. -However there is currently no filesystem\-independent -interface for an application to discover these restrictions for a given -file or filesystem. -Some filesystems provide their own interfaces -for doing so, for example the +The handling of misaligned +.B O_DIRECT +I/Os also varies; they can either fail with +.B EINVAL +or fall back to buffered I/O. +.PP +Since Linux 6.1, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; see +.BR statx (2). +.PP +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, for example the .B XFS_IOC_DIOINFO operation in .BR xfsctl (3). +.B STATX_DIOALIGN
Quoted 8 lines
man2/open.2 of user-space buffers and the file offset of I/Os. · line 1749
Quoted 8 lines
man2/open.2 +1
-6+should be used instead when it is available. .PP -Under Linux 2.4, transfer sizes, the alignment of the user buffer, -and the file offset must all be multiples of the logical block size -of the filesystem. -Since Linux 2.6.0, alignment to the logical block size of the -underlying storage (typically 512 bytes) suffices. -The logical block size can be determined using the
I'm not so familiar with semantic newlines-- is there an automated reflow program that fixes these problems mechanically, or is this expected to be performed manually by manpage authors?
If manually, do the items in a comma-separated list count as clauses?
Would the next two paragraphs of this email reformat into semantic newlines like so?
In the source of a manual page,
new sentences should be started on new lines,
long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on),
and long clauses should be split at phrase boundaries.
This convention,
sometimes known as "semantic newlines",
makes it easier to see the effect of patches,
which often operate at the level of individual sentences, clauses, or phrases.
Do we still line-wrap at 72^W74^W78^W80 columns?
and would the proposed manpage text read:
If none of the above is available,
then direct I/O support and alignment restrictions can only be assumed from known characteristics of the filesystem,
the individual file,
the underlying storage device(s),
and the kernel version.
In Linux 2.4,
most block device based filesystems require that the file offset and the length and memory address of all I/O segments be multiples of the filesystem block size
(typically 4096 bytes).
In Linux 2.6.0,
this was relaxed to the logical block size of the block device (typically 512 bytes).
A block device's logical block size can be determined using the .BR ioctl (2)
.B BLKSSZGET
operation or from the shell using the command:
--D
Quoted 93 lines
man2/open.2 of user-space buffers and the file offset of I/Os. · line 1762
Quoted 1 line
man2/open.2 +1
-0+If none of the above is available, then direct I/O support and alignmentPlease use semantic newlines.
See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase bound‐ aries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases.Quoted 38 lines
man2/open.2 +8
-0+restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:man2/statx.2 +7
-0@@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in@@ -247,6 +252,8 @@ STATX_BTIME Want stx_btime STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. It is deprecated and should not be used. STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) .TE .in .PPman2/statx.2 This is the same number reported by · line 420
Quoted 7 lines
man2/statx.2 +4
-0@@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT ).RB and remove the "".
man2/statx.2 This is the same number reported by · line 424
Quoted 4 lines
man2/statx.2 +4
-0+on this file, or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align.RI
Quoted 19 lines
man2/statx.2 +14
-0+and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).base-commit:
bc28d289e5066fc626df260bafc249846a0f6ae6Signature · 1 line
<http://www.alejandro-colomar.es/>
Semantic newlines (was: [man-pages PATCH v3] statx.2, open.2: document STATX_DIOALIGN)
Hi Darrick,
Quoted 2 lines · Darrick J. Wong
I'm not so familiar with semantic newlines-- is there an automated
The following commit contains interesting details about them and their origins:
Quoted 2 lines
reflow program that fixes these problems mechanically, or is this expected to be performed manually by manpage authors?
I don't know of a reflow program that fixes this. The biggest issue is that
parsing natural language is not exactly easy.
So, it is expected to be performed manually by authors.
Quoted 2 lines
If manually, do the items in a comma-separated list count as clauses?
It depends.
Pedantically, yes;
but we evaluate it case by case, depending on the length of each sentence and the existence of subordinate clauses. So author taste is important there and respected.
Quoted 15 lines
Would the next two paragraphs of this email reformat into semantic newlines like so?
In the source of a manual page,
new sentences should be started on new lines,
long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on),
and long clauses should be split at phrase boundaries.
This convention,
sometimes known as "semantic newlines",
makes it easier to see the effect of patches,
which often operate at the level of individual sentences, clauses, or phrases.
Quoted 98 lines
--D
Quoted 93 lines
Quoted 1 line
+If none of the above is available, then direct I/O support and alignment
Please use semantic newlines.
See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase bound‐ aries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases.Quoted 38 lines
man2/open.2 +8
-0+restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:man2/statx.2 +7
-0@@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in@@ -247,6 +252,8 @@ STATX_BTIME Want stx_btime STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. It is deprecated and should not be used. STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) .TE .in .PPman2/statx.2 This is the same number reported by · line 420
Quoted 7 lines
man2/statx.2 +4
-0@@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT ).RB and remove the "".
man2/statx.2 This is the same number reported by · line 424
Quoted 4 lines
man2/statx.2 +4
-0+on this file, or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align.RI
Quoted 18 lines
man2/statx.2 +14
-0+and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).Quoted 1 line
base-commit:
bc28d289e5066fc626df260bafc249846a0f6ae6
Yes, that would be correct;
in fact,
you almost matched the actual source code of the manual page. There are two differences:
one comma at which we don't break (but we could), and also we break the last line before the list.
See the source code here:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/man-pages.7#n612>
Quoted 1 line
Do we still line-wrap at 72^W74^W78^W80 columns?
Yes, 80 is a strong limit.
Normally,
breaking at the level of clauses
will leave very few lines passing that limit.
When there's such a case,
you can break further at the level of phrases,
and I doubt any line will pass the 80-col boundary after that.
Quoted 11 lines
and would the proposed manpage text read:
If none of the above is available,
then direct I/O support and alignment restrictions can only be assumed from known characteristics of the filesystem,
the individual file,
the underlying storage device(s),
and the kernel version.
In Linux 2.4,
most block device based filesystems require that the file offset and the
block device based would need some '-' as it's a compound adjective (I don't know the exact rules in English when there are more than two words forming such an adjective, please check).
I would break after 'require that'.
Quoted 1 line
length and memory address of all I/O segments be multiples of the
And right before 'be', I think.
Quoted 9 lines
filesystem block size (typically 4096 bytes). In Linux 2.6.0, this was relaxed to the logical block size of the block device (typically 512 bytes). A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command:
But mostly looks good.
Cheers,
Alex
Signature · 1 line
<http://www.alejandro-colomar.es/>
Eric Biggers
maintainerHi Alejandro,
Quoted 4 lines · Alejandro Colomar
Quoted 1 line
+If none of the above is available, then direct I/O support and alignment
Please use semantic newlines.
Quoted 10 lines
See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase bound‐ aries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases.
I tried to do this in v4. It seems very arbitrary, though, so if you want further changes to the newlines I recommend just making them when committing the patch.
Note that a better way to review changes to text is to do a word diff instead of a line diff.
- Eric