man: read/write page updates

- Add note on some limitations of using -1 for the offset, indicating
  that the application wants to use the current file position rather
  than pass on in.

- A few style fixups.

Signed-off-by: Jens Axboe <axboe@kernel.dk>

6 files changed, 54 insertions, 24 deletions

diff --git a/man/io_uring_prep_read.3 b/man/io_uring_prep_read.3
index 4fc1420..de3067d 100644
--- a/man/io_uring_prep_read.3
+++ b/man/io_uring_prep_read.3
@@ -29,11 +29,15 @@ into the buffer
 at the specified
 .I offset.
 
-On files that support seeking, if the offset is set to -1, the read operation
-commences at the file offset, and the file offset is incremented by the number
-of bytes read. See
+On files that support seeking, if the offset is set to
+.B -1,
+the read operation commences at the file offset, and the file offset is
+incremented by the number of bytes read. See
 .BR read (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.
 
diff --git a/man/io_uring_prep_readv.3 b/man/io_uring_prep_readv.3
index b08ccb9..8e66bce 100644
--- a/man/io_uring_prep_readv.3
+++ b/man/io_uring_prep_readv.3
@@ -18,7 +18,8 @@ io_uring_prep_readv  - prepare vector I/O read request
 .PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_readv() prepares a vectored IO read request. The submission queue entry
+The io_uring_prep_readv() prepares a vectored IO read request. The submission
+queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -29,11 +30,15 @@ into the
 array at the specified
 .I offset.
 
-On files that support seeking, if the offset is set to -1, the read operation
-commences at the file offset, and the file offset is incremented by the number
-of bytes read. See
+On files that support seeking, if the offset is set to
+.B -1,
+the read operation commences at the file offset, and the file offset is
+incremented by the number of bytes read. See
 .BR read (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.
 
diff --git a/man/io_uring_prep_readv2.3 b/man/io_uring_prep_readv2.3
index b05f36e..0d9d200 100644
--- a/man/io_uring_prep_readv2.3
+++ b/man/io_uring_prep_readv2.3
@@ -21,7 +21,8 @@ io_uring_prep_readv2 - prepare vector I/O read request with flags
 .PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_readv2() prepares a vectored IO read request. The submission queue entry
+The io_uring_prep_readv2() prepares a vectored IO read request. The submission
+queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -49,7 +50,9 @@ per-IO O_DSYNC
 per-IO O_SYNC
 .TP
 .B RWF_NOWAIT
-per-IO, return -EAGAIN if operation would block
+per-IO, return
+.B -EAGAIN
+if operation would block
 .TP
 .B RWF_APPEND
 per-IO O_APPEND
@@ -60,7 +63,10 @@ On files that support seeking, if the offset is set to
 the read operation commences at the file offset, and the file offset is
 incremented by the number of bytes read. See
 .BR read (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.
 
diff --git a/man/io_uring_prep_write.3 b/man/io_uring_prep_write.3
index 25c5301..4bbf7e0 100644
--- a/man/io_uring_prep_write.3
+++ b/man/io_uring_prep_write.3
@@ -29,11 +29,15 @@ from the buffer
 at the specified
 .I offset.
 
-On files that support seeking, if the offset is set to -1, the write operation
-commences at the file offset, and the file offset is incremented by the number
-of bytes written. See
+On files that support seeking, if the offset is set to
+.B -1,
+the write operation commences at the file offset, and the file offset is
+incremented by the number of bytes written. See
 .BR write (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.
 
diff --git a/man/io_uring_prep_writev.3 b/man/io_uring_prep_writev.3
index 99652d3..e11f656 100644
--- a/man/io_uring_prep_writev.3
+++ b/man/io_uring_prep_writev.3
@@ -18,7 +18,8 @@ io_uring_prep_writev  - prepare vector I/O write request
 .PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_writev() prepares a vectored IO write request. The submission queue entry
+The io_uring_prep_writev() prepares a vectored IO write request. The submission
+queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -29,11 +30,15 @@ from the
 array at the specified
 .I offset.
 
-On files that support seeking, if the offset is set to -1, the write operation
-commences at the file offset, and the file offset is incremented by the number
-of bytes written. See
+On files that support seeking, if the offset is set to
+.B -1,
+the write operation commences at the file offset, and the file offset is
+incremented by the number of bytes written. See
 .BR write (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.
 
diff --git a/man/io_uring_prep_writev2.3 b/man/io_uring_prep_writev2.3
index 4a994d0..712c4ba 100644
--- a/man/io_uring_prep_writev2.3
+++ b/man/io_uring_prep_writev2.3
@@ -20,7 +20,8 @@ io_uring_prep_writev2 - prepare vector I/O write request with flags
 .PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_writev2() prepares a vectored IO write request. The submission queue entry
+The io_uring_prep_writev2() prepares a vectored IO write request. The
+submission queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -48,7 +49,9 @@ per-IO O_DSYNC
 per-IO O_SYNC
 .TP
 .B RWF_NOWAIT
-per-IO, return -EAGAIN if operation would block
+per-IO, return
+.B -EAGAIN
+if operation would block
 .TP
 .B RWF_APPEND
 per-IO O_APPEND
@@ -59,7 +62,10 @@ On files that support seeking, if the offset is set to
 the write operation commences at the file offset, and the file offset is
 incremented by the number of bytes written. See
 .BR write (2)
-for more details.
+for more details. Note that for an async API, reading and updating the
+current file offset may result in unpredictable behavior, unless access
+to the file is serialized. It is not encouraged to use this feature, if it's
+possible to provide the desired IO offset from the application or library.
 
 On files that are not capable of seeking, the offset is ignored.