From: Jens Axboe <axboe@kernel.dk>
Date: Thu, 13 Jul 2017 15:39:01 +0000 (-0600)
Subject: Update documentation for write_hint
X-Git-Tag: fio-3.0~36
X-Git-Url: https://git.kernel.dk/?p=fio.git;a=commitdiff_plain;h=8f4b9f2475a4524067b6a0662aff006783919922;hp=43f466e667a8bcfc58c1c69b0897fe0345c34841

Update documentation for write_hint

We no longer have fadvise_stream, adapt the documentation to
describe the stable 'write_hint' option.

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

diff --git a/HOWTO b/HOWTO
index 0b80a623..e5446340 100644
--- a/HOWTO
+++ b/HOWTO
@@ -1093,11 +1093,29 @@ I/O type
 		**random**
 			Advise using **FADV_RANDOM**.
 
-.. option:: fadvise_stream=int
+.. option:: write_hint=str
 
-	Use :manpage:`posix_fadvise(2)` to advise the kernel what stream ID the
-	writes issued belong to. Only supported on Linux. Note, this option may
-	change going forward.
+	Use :manpage:`fcntl(2)` to advise the kernel what life time to expect
+	from a write. Only supported on Linux, as of version 4.13. Accepted
+	values are:
+
+		**none**
+			No particular life time associated with this file.
+
+		**short**
+			Data written to this file has a short life time.
+
+		**medium**
+			Data written to this file has a medium life time.
+
+		**long**
+			Data written to this file has a long life time.
+
+		**extreme**
+			Data written to this file has a very long life time.
+
+	The values are all relative to each other, and no absolute meaning
+	should be associated with them.
 
 .. option:: offset=int
 
diff --git a/fio.1 b/fio.1
index bc477a2e..5da9ecfc 100644
--- a/fio.1
+++ b/fio.1
@@ -564,10 +564,30 @@ Advise using \fBFADV_RANDOM\fR
 .RE
 .RE
 .TP
-.BI fadvise_stream \fR=\fPint
-Use \fBposix_fadvise\fR\|(2) to advise the kernel what stream ID the
-writes issued belong to. Only supported on Linux. Note, this option
-may change going forward.
+.BI write_hint \fR=\fPstr
+Use \fBfcntl\fR|(2) to advise the kernel what life time to expect from a write.
+Only supported on Linux, as of version 4.13. The values are all relative to
+each other, and no absolute meaning should be associated with them. Accepted
+values are:
+.RS
+.RS
+.TP
+.B none
+No particular life time associated with this file.
+.TP
+.B short
+Data written to this file has a short life time.
+.TP
+.B medium
+Data written to this file has a medium life time.
+.TP
+.B long
+Data written to this file has a long life time.
+.TP
+.B extreme
+Data written to this file has a very long life time.
+.RE
+.RE
 .TP
 .BI size \fR=\fPint
 Total size of I/O for this job.  \fBfio\fR will run until this many bytes have