summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJens Axboe <axboe@kernel.dk>2022-02-23 16:03:34 -0700
committerJens Axboe <axboe@kernel.dk>2022-02-23 16:03:34 -0700
commit071ad6354d1e0a6da48469fbbd750cc4ca400a2c (patch)
tree9342ea15c55b5236b2981a6290affcc2cdcb4e90
parent540e837e5fc125b85ea67401117fc601997958f9 (diff)
downloadliburing-071ad6354d1e0a6da48469fbbd750cc4ca400a2c.tar.gz
liburing-071ad6354d1e0a6da48469fbbd750cc4ca400a2c.tar.bz2
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>
-rw-r--r--man/io_uring_prep_read.312
-rw-r--r--man/io_uring_prep_readv.315
-rw-r--r--man/io_uring_prep_readv2.312
-rw-r--r--man/io_uring_prep_write.312
-rw-r--r--man/io_uring_prep_writev.315
-rw-r--r--man/io_uring_prep_writev2.312
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.