From da523c365a075b89f79e9de6fd6df507604ef3f5 Mon Sep 17 00:00:00 2001
From: Zoraaver Singh <zoraaver@amazon.co.uk>
Date: Thu, 5 Oct 2023 09:20:05 +0100
Subject: [PATCH] Add caveat about support for sync flags

Since sync flag functionality is entirely dependent on the host
platform, add a caveat for each sync flag, warning that functions may
return ENOTSUP if an unsupported sync flag is set.
---
 legacy/preview1/docs.md | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/legacy/preview1/docs.md b/legacy/preview1/docs.md
index 7efd7f29..827a1ec5 100644
--- a/legacy/preview1/docs.md
+++ b/legacy/preview1/docs.md
@@ -663,7 +663,11 @@ Append mode: Data written to the file is always appended to the file's end.
 Bit: 0
 
 - <a href="#fdflags.dsync" name="fdflags.dsync"></a> `dsync`: `bool`
-Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.
+Write according to synchronized I/O data integrity completion. Only the data
+stored in the file is synchronized.  This feature is not available on all
+platforms and therefore [`path_open`](#path_open) and other such functions which
+accept [`fdflags`](#fdflags) may return [`errno.notsup`](#errno.notsup) in the
+case that this flag is set.
 
 Bit: 1
 
@@ -674,13 +678,20 @@ Bit: 2
 
 - <a href="#fdflags.rsync" name="fdflags.rsync"></a> `rsync`: `bool`
 Synchronized read I/O operations.
+This feature is not available on all platforms and therefore
+[`path_open`](#path_open) and other such functions which accept
+[`fdflags`](#fdflags) may return [`errno.notsup`](#errno.notsup) in the case
+that this flag is set.
 
 Bit: 3
 
 - <a href="#fdflags.sync" name="fdflags.sync"></a> `sync`: `bool`
-Write according to synchronized I/O file integrity completion. In
-addition to synchronizing the data stored in the file, the implementation
-may also synchronously update the file's metadata.
+Write according to synchronized I/O file integrity completion. In addition to
+synchronizing the data stored in the file, the implementation may also
+synchronously update the file's metadata.  This feature is not available on all
+platforms and therefore [`path_open`](#path_open) and other such functions which
+accept [`fdflags`](#fdflags) may return [`errno.notsup`](#errno.notsup) in the
+case that this flag is set.
 
 Bit: 4