From: Eric Biggers <ebiggers@kernel.org>
To: linux-man@vger.kernel.org
Cc: linux-fsdevel@vger.kernel.org, linux-api@vger.kernel.org,
linux-kernel@vger.kernel.org, linux-ext4@vger.kernel.org,
linux-f2fs-devel@lists.sourceforge.net,
linux-xfs@vger.kernel.org, linux-fscrypt@vger.kernel.org,
linux-block@vger.kernel.org,
"Darrick J. Wong" <djwong@kernel.org>
Subject: [man-pages PATCH v3] statx.2, open.2: document STATX_DIOALIGN
Date: Tue, 4 Oct 2022 10:43:07 -0700 [thread overview]
Message-ID: <20221004174307.6022-1-ebiggers@kernel.org> (raw)
From: Eric Biggers <ebiggers@google.com>
Document the STATX_DIOALIGN support for statx()
(https://git.kernel.org/linus/725737e7c21d2d25).
Reviewed-by: Darrick J. Wong <djwong@kernel.org>
Signed-off-by: Eric Biggers <ebiggers@google.com>
---
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(-)
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
+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 )
+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
--
2.37.3
next reply other threads:[~2022-10-04 17:44 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-04 17:43 Eric Biggers [this message]
2022-10-07 2:35 ` [man-pages PATCH v3] statx.2, open.2: document STATX_DIOALIGN Darrick J. Wong
2022-10-08 1:56 ` Alejandro Colomar
2022-10-10 15:22 ` Darrick J. Wong
2022-10-10 16:15 ` Semantic newlines (was: [man-pages PATCH v3] statx.2, open.2: document STATX_DIOALIGN) Alejandro Colomar
2022-10-11 23:02 ` [man-pages PATCH v3] statx.2, open.2: document STATX_DIOALIGN Eric Biggers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221004174307.6022-1-ebiggers@kernel.org \
--to=ebiggers@kernel.org \
--cc=djwong@kernel.org \
--cc=linux-api@vger.kernel.org \
--cc=linux-block@vger.kernel.org \
--cc=linux-ext4@vger.kernel.org \
--cc=linux-f2fs-devel@lists.sourceforge.net \
--cc=linux-fscrypt@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=linux-xfs@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).