Debian Codegraph @

upstream/debian-unstable/man2/F_GET_RW_HINT.2const

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