1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH F_GET_RW_HINT 2const 2025-07-20 "Linux man-pages (unreleased)"
.SH NAME
F_GET_RW_HINT,
F_SET_RW_HINT,
F_GET_FILE_RW_HINT,
F_SET_FILE_RW_HINT
\-
get/set file read/write hints
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <fcntl.h>
.P
.BI "int fcntl(int " fd ", F_GET_RW_HINT, uint64_t *" arg );
.BI "int fcntl(int " fd ", F_SET_RW_HINT, uint64_t *" arg );
.BI "int fcntl(int " fd ", F_GET_FILE_RW_HINT, uint64_t *" arg );
.BI "int fcntl(int " fd ", F_GET_FILE_RW_HINT, uint64_t *" arg );
.fi
.SH DESCRIPTION
Write lifetime hints can be used to inform the kernel about the relative
expected lifetime of writes on a given inode or
via a particular open file description.
(See
.BR open (2)
for an explanation of open file descriptions.)
In this context, the term "write lifetime" means
the expected time the data will live on media, before
being overwritten or erased.
.P
An application may use the different hint values specified below to
separate writes into different write classes,
so that multiple users or applications running on a single storage back-end
can aggregate their I/O patterns in a consistent manner.
However, there are no functional semantics implied by these flags,
and different I/O classes can use the write lifetime hints
in arbitrary ways, so long as the hints are used consistently.
.P
The following operations can be applied to the file descriptor,
.IR fd :
.TP
.B F_GET_RW_HINT
Returns the value of the read/write hint associated with the underlying inode
referred to by
.IR fd .
.TP
.B F_SET_RW_HINT
Sets the read/write hint value associated with the
underlying inode referred to by
.IR fd .
This hint persists until either it is explicitly modified or
the underlying filesystem is unmounted.
.TP
.B F_GET_FILE_RW_HINT
Returns the value of the read/write hint associated with
the open file description referred to by
.IR fd .
.TP
.B F_SET_FILE_RW_HINT
Sets the read/write hint value associated with the open file description
referred to by
.IR fd .
.P
If an open file description has not been assigned a read/write hint,
then it shall use the value assigned to the inode, if any.
.P
The following read/write
hints are supported:
.TP
.B RWH_WRITE_LIFE_NOT_SET
No specific hint has been set.
This is the default value.
.TP
.B RWH_WRITE_LIFE_NONE
No specific write lifetime is associated with this file or inode.
.TP
.B RWH_WRITE_LIFE_SHORT
Data written to this inode or via this open file description
is expected to have a short lifetime.
.TP
.B RWH_WRITE_LIFE_MEDIUM
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_SHORT .
.TP
.B RWH_WRITE_LIFE_LONG
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_MEDIUM .
.TP
.B RWH_WRITE_LIFE_EXTREME
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_LONG .
.P
All the write-specific hints are relative to each other,
and no individual absolute meaning should be attributed to them.
.SH RETURN VALUE
Zero.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
See
.BR fcntl (2).
.SH STANDARDS
Linux.
.SH HISTORY
Linux 4.13.
.SH SEE ALSO
.BR fcntl (2)
|
