Hi Eric, On 10/4/22 19:43, Eric Biggers wrote:
From: Eric Biggers <ebiggers@xxxxxxxxxx> Document the STATX_DIOALIGN support for statx() (https://git.kernel.org/linus/725737e7c21d2d25). Reviewed-by: Darrick J. Wong <djwong@xxxxxxxxxx> Signed-off-by: Eric Biggers <ebiggers@xxxxxxxxxx>
Please see some formatting comments below.
--- I'm resending this now that support for STATX_DIOALIGN has been merged upstream.
Thanks. Cheers, Alex
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(-)
diff --git a/man2/open.2 b/man2/open.2
index deba7e4ea..b8617e0d2 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -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
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.
+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:
diff --git a/man2/statx.2 b/man2/statx.2
index 0d1b4591f..50397057d 100644
--- a/man2/statx.2
+++ b/man2/statx.2
@@ -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 )
.RB and remove the "".
+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
+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
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
