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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
//! Clearing `FD_CLOEXEC` on a descriptor the handover carries, and reading
//! it back.
//!
//! Every descriptor in the handover blob passes through [`keep_across_exec`]
//! exactly once, deliberately, before the daemon `execv`s its successor.
//! Everything the daemon opens is close-on-exec by default (verified
//! against pinned `mio`, `tokio` and `std` sources), so a descriptor this
//! module never touches is closed by the kernel at the exec boundary and
//! silently dropped from the new image. For a sheep's stdout read end, that
//! does not lose the sheep's output: the child blocks on `write()` once the
//! 64KiB pipe buffer fills, and hangs, which reads as an application bug
//! not a shep one.
use io;
use ;
use ;
/// Clear `FD_CLOEXEC` on `fd`, so it survives this process's next
/// `execve`.
///
/// Reads the descriptor's current flags with `F_GETFD`, clears only the
/// `FD_CLOEXEC` bit, and writes the result back with `F_SETFD`. A bare
/// `F_SETFD(FdFlag::empty())` would clobber any other flag the descriptor
/// carries, and would not be idempotent: a second call would re-derive
/// `empty()` from whatever the first call left rather than from the
/// descriptor's real flags, so the operation would happen to look
/// idempotent only because it always writes the same clobbered value.
///
/// Do not call this on a descriptor the successor will not adopt: every fd
/// left `FD_CLOEXEC`-clear leaks into the new process image across the
/// exec, whether or not the handover blob names it.
///
/// # Errors
///
/// Returns an error if `fcntl` fails, which on a valid open descriptor
/// should not happen in practice.
/// [`keep_across_exec`], for a descriptor known only by its number.
///
/// The handover blob names descriptors as numbers, not as borrows, and the
/// borrowed form is reached only through `BorrowedFd::borrow_raw`, which is
/// unsafe and would have to live in `sys.rs` (IR-22/23). `fcntl` on a
/// number needs neither, so the number is the primitive here and the
/// borrowed form delegates to it.
///
/// The same warning applies: call this only for a descriptor the successor
/// will adopt.
///
/// # Errors
///
/// Returns an error if `fcntl` fails, which is what a number naming no open
/// descriptor looks like.
/// Set `FD_CLOEXEC` on `fd` again, undoing a [`keep_raw_across_exec`] whose
/// exec never happened.
///
/// The inverse of that function, bit for bit: reads the current flags,
/// sets only `FD_CLOEXEC`, writes them back. Nothing else the descriptor
/// carries is disturbed.
///
/// Restoring is the right direction and not merely the symmetric one.
/// Everything the daemon opens is close-on-exec at creation, per this
/// module's own preamble, so the flag this puts back is the flag the
/// descriptor had before the handover cleared it.
///
/// # Errors
///
/// Returns an error if `fcntl` fails, which on a valid open descriptor
/// should not happen in practice.
/// Duplicate `fd` onto a fresh number, for a caller that needs to inspect a
/// descriptor it must not take.
///
/// The duplicate refers to the same open file description, so every question
/// an adoption asks answers identically through it: what kind of object it
/// is, which direction it is open for, whether a socket is connected, which
/// status flags it carries. What it does not share is ownership, and that is
/// the whole point — closing the duplicate leaves the original open and
/// still owned by whoever in this process owns it.
///
/// `F_DUPFD_CLOEXEC` rather than a bare `dup(2)`, and both halves of that
/// are load-bearing here. The floor keeps a duplicate off stdio, so
/// [`crate::sys::adoptable_fd`] cannot refuse it as reserved and report a
/// problem the blob does not have. Close-on-exec means a duplicate that
/// somehow outlived its inspection still cannot leak into a successor's
/// image, which is precisely the failure [`close_raw_after_exec`] exists to
/// undo for the named descriptors.
///
/// # Errors
///
/// Returns an error if `fcntl` fails, which is what a number naming no open
/// descriptor looks like, and what a process at its descriptor limit looks
/// like too.
/// Whether `fd` currently survives an `execve` (i.e. `FD_CLOEXEC` is
/// clear).
///
/// # Errors
///
/// Returns an error if `fcntl` fails, which on a valid open descriptor
/// should not happen in practice.