Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_sys/src/notify/follow.rs

9.4 KiB, 1 run

created by r1870400018:76749, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! Following files across renames, by anyone, through held descriptors.
2//!
3//! Each followed file is held by an `O_PATH` descriptor, and its inotify watch is added through
4//! `/proc/self/fd/<held>`, never a path string, so the watch is on the file the caller was given
5//! even if it was renamed before the watch went on. The mask is `IN_MOVE_SELF`, `IN_DELETE_SELF`
6//! and `IN_ATTRIB`: while the descriptor is held the file's inode cannot go, so `IN_DELETE_SELF`
7//! does not fire on an unlink or an atomic save over it, and the drop of its link count to zero
8//! shows as `IN_ATTRIB` instead (BR-4e S1, probe 4). On any event the held link is read again
9//! and the difference reported. On `IN_Q_OVERFLOW` every held link is read again.
10//!
11//! A held descriptor keeps its mount busy: [`Follower::unfollow_under`] lets a mount go.
12//! A limit met, `follow_max`, the inotify watches (`ENOSPC`) or the descriptors (`EMFILE`,
13//! `ENFILE`), is answered as [`Followed::Full`], never swallowed.
14//!
15//! The system calls come from `nix`, which owns the `unsafe` this crate forbids.
16
17use oxedyne_fe2o3_core::prelude::*;
18
19use nix::{
20 errno::Errno,
21 fcntl::{
22 open,
23 OFlag,
24 },
25 sys::{
26 inotify::{
27 AddWatchFlags,
28 InitFlags,
29 Inotify,
30 WatchDescriptor,
31 },
32 stat::{
33 fstat,
34 Mode,
35 },
36 },
37};
38
39use std::{
40 collections::BTreeMap,
41 fs,
42 os::fd::{
43 AsFd,
44 AsRawFd,
45 BorrowedFd,
46 OwnedFd,
47 },
48 path::{
49 Path,
50 PathBuf,
51 },
52};
53
54/// One followed file.
55#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
56pub struct FollowId(WatchDescriptor);
57
58#[derive(Clone, Copy, Debug, Eq, PartialEq)]
59pub enum Limit {
60 FollowMax(usize), // The follower's own bound.
61 Watches, // inotify_add_watch gave ENOSPC: fs.inotify.max_user_watches.
62 Descriptors, // EMFILE or ENFILE on the O_PATH open.
63}
64
65#[derive(Clone, Copy, Debug, Eq, PartialEq)]
66pub enum Followed {
67 Held(FollowId),
68 Already(FollowId), // The same file is followed already.
69 Full(Limit),
70}
71
72#[derive(Clone, Debug, Eq, PartialEq)]
73pub enum Change {
74 Moved { id: FollowId, old: PathBuf, new: PathBuf },
75 Gone { id: FollowId, last: PathBuf }, // Unlinked or saved over; no longer followed.
76 Dropped { id: FollowId, last: PathBuf }, // The kernel removed the watch; no longer followed.
77 Overflow, // The queue overflowed; the changes after it are from a full re-read.
78}
79
80struct Held {
81 fd: OwnedFd,
82 path: PathBuf,
83}
84
85pub struct Follower {
86 ino: Inotify,
87 held: BTreeMap<WatchDescriptor, Held>,
88 max: usize,
89}
90
91// fixed: the suffix the kernel's d_path gives an unlinked file.
92const DELETED: &str = " (deleted)";
93
94impl Follower {
95 /// A follower that holds at most `max` files, which must sit below the process's
96 /// `RLIMIT_NOFILE` with room for its other descriptors.
97 pub fn new(max: usize) -> Outcome<Self> {
98 let ino = res!(Inotify::init(InitFlags::IN_NONBLOCK | InitFlags::IN_CLOEXEC).map_err(|e|
99 err!("inotify_init1: {}.", e; IO, System)));
100 Ok(Self { ino, held: BTreeMap::new(), max })
101 }
102
103 /// Readable (`POLLIN`) when events wait; then call [`Self::read`].
104 pub fn fd(&self) -> BorrowedFd<'_> {
105 self.ino.as_fd()
106 }
107
108 pub fn len(&self) -> usize {
109 self.held.len()
110 }
111
112 pub fn is_empty(&self) -> bool {
113 self.held.is_empty()
114 }
115
116 /// The followed file's path as last read.
117 pub fn path(&self, id: FollowId) -> Option<&Path> {
118 self.held.get(&id.0).map(|h| h.path.as_path())
119 }
120
121 /// The held `O_PATH` descriptor, for `statx` and the host-path resolver.
122 pub fn held_fd(&self, id: FollowId) -> Option<BorrowedFd<'_>> {
123 self.held.get(&id.0).map(|h| h.fd.as_fd())
124 }
125
126 pub fn ids(&self) -> Vec<FollowId> {
127 self.held.keys().map(|w| FollowId(*w)).collect()
128 }
129
130 /// Follows the file `path` names now.
131 pub fn follow_path(&mut self, path: &Path) -> Outcome<Followed> {
132 self.hold(path)
133 }
134
135 /// Follows the file `fd` is open on, wherever it now is, such as a fanotify event's.
136 pub fn follow_fd(&mut self, fd: BorrowedFd<'_>) -> Outcome<Followed> {
137 self.hold(Path::new(&format!("/proc/self/fd/{}", fd.as_raw_fd())))
138 }
139
140 fn hold(&mut self, at: &Path) -> Outcome<Followed> {
141 if self.held.len() >= self.max {
142 return Ok(Followed::Full(Limit::FollowMax(self.max)));
143 }
144 let fd = match open(at, OFlag::O_PATH | OFlag::O_CLOEXEC, Mode::empty()) {
145 Ok(fd) => fd,
146 Err(Errno::EMFILE | Errno::ENFILE) => return Ok(Followed::Full(Limit::Descriptors)),
147 Err(e) => return Err(err!("Opening '{}' O_PATH: {}.",
148 at.display(), e; IO, File, Read)),
149 };
150 let proc_path = format!("/proc/self/fd/{}", fd.as_raw_fd());
151 let mask = AddWatchFlags::IN_MOVE_SELF | AddWatchFlags::IN_DELETE_SELF | AddWatchFlags::IN_ATTRIB;
152 let wd = match self.ino.add_watch(proc_path.as_str(), mask) {
153 Ok(wd) => wd,
154 Err(Errno::ENOSPC) => return Ok(Followed::Full(Limit::Watches)),
155 Err(e) => return Err(err!("inotify_add_watch on '{}': {}.",
156 at.display(), e; IO, System)),
157 };
158 if self.held.contains_key(&wd) {
159 return Ok(Followed::Already(FollowId(wd)));
160 }
161 let path = res!(read_held(&fd));
162 self.held.insert(wd, Held { fd, path });
163 Ok(Followed::Held(FollowId(wd)))
164 }
165
166 /// Stops following `id`, answering its last path.
167 pub fn unfollow(&mut self, id: FollowId) -> Option<PathBuf> {
168 match self.held.remove(&id.0) {
169 Some(h) => {
170 // The watch may have gone with its file already; its removal is then moot.
171 let _ = self.ino.rm_watch(id.0);
172 Some(h.path)
173 }
174 None => None,
175 }
176 }
177
178 /// Stops following every file whose last path is under `prefix`, so its mount can go.
179 pub fn unfollow_under(&mut self, prefix: &Path) -> Vec<(FollowId, PathBuf)> {
180 let ids: Vec<FollowId> = self.held.iter()
181 .filter(|(_, h)| h.path.starts_with(prefix))
182 .map(|(w, _)| FollowId(*w))
183 .collect();
184 ids.into_iter().filter_map(|id| self.unfollow(id).map(|p| (id, p))).collect()
185 }
186
187 /// Reads the events waiting and answers what changed, none if nothing did.
188 pub fn read(&mut self) -> Outcome<Vec<Change>> {
189 let mut out = Vec::new();
190 loop {
191 let evs = match self.ino.read_events() {
192 Ok(v) => v,
193 Err(Errno::EAGAIN) => break,
194 Err(e) => return Err(err!("Reading inotify events: {}.", e; IO, Read)),
195 };
196 if evs.is_empty() { break; }
197 for ev in evs {
198 if ev.mask.contains(AddWatchFlags::IN_Q_OVERFLOW) {
199 out.push(Change::Overflow);
200 let mut all = res!(self.resync());
201 out.append(&mut all);
202 continue;
203 }
204 if !self.held.contains_key(&ev.wd) {
205 continue; // Unfollowed already, its IN_IGNORED arriving after.
206 }
207 let id = FollowId(ev.wd);
208 if ev.mask.contains(AddWatchFlags::IN_IGNORED) {
209 if let Some(h) = self.held.remove(&ev.wd) {
210 out.push(Change::Dropped { id, last: h.path });
211 }
212 continue;
213 }
214 if ev.mask.contains(AddWatchFlags::IN_DELETE_SELF) {
215 if let Some(last) = self.unfollow(id) {
216 out.push(Change::Gone { id, last });
217 }
218 continue;
219 }
220 if let Some(c) = res!(self.check(id)) {
221 out.push(c);
222 }
223 }
224 }
225 Ok(out)
226 }
227
228 /// Reads every held link again and answers each difference.
229 pub fn resync(&mut self) -> Outcome<Vec<Change>> {
230 let mut out = Vec::new();
231 for id in self.ids() {
232 if let Some(c) = res!(self.check(id)) {
233 out.push(c);
234 }
235 }
236 Ok(out)
237 }
238
239 fn check(&mut self, id: FollowId) -> Outcome<Option<Change>> {
240 let (now, nlink) = match self.held.get(&id.0) {
241 Some(h) => {
242 let now = res!(read_held(&h.fd));
243 let st = res!(fstat(&h.fd).map_err(|e| err!("fstat of a held file: {}.", e; IO, System)));
244 (now, st.st_nlink)
245 }
246 None => return Ok(None),
247 };
248 if nlink == 0 || now.to_string_lossy().ends_with(DELETED) {
249 return Ok(self.unfollow(id).map(|last| Change::Gone { id, last }));
250 }
251 match self.held.get_mut(&id.0) {
252 Some(h) if h.path != now => {
253 let old = std::mem::replace(&mut h.path, now.clone());
254 Ok(Some(Change::Moved { id, old, new: now }))
255 }
256 _ => Ok(None),
257 }
258 }
259}
260
261fn read_held(fd: &OwnedFd) -> Outcome<PathBuf> {
262 let p = format!("/proc/self/fd/{}", fd.as_raw_fd());
263 fs::read_link(&p).map_err(|e| err!("Reading the held link '{}': {}.", p, e; IO, Read))
264}