Mercurial > crates > nonstick

comparison src/handle.rs @ 174:9e4ce1631bd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Dramatically expand documentation.
author Paul Fisher <paul@pfish.zone>
date Tue, 29 Jul 2025 18:58:27 -0400
parents e27c5c667a5a
children
comparison
equal deleted inserted replaced
173:46e8ce5cd5d1 174:9e4ce1631bd3
48 fn username(&mut self, prompt: Option<&OsStr>) -> Result<OsString>; 48 fn username(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
49 49
50 /// The contents of the environment to set for the logged-in user. 50 /// The contents of the environment to set for the logged-in user.
51 /// 51 ///
52 /// # References 52 /// # References
53 ///
54 #[doc = linklist!(pam_getenv: adg, mwg, _std)] 53 #[doc = linklist!(pam_getenv: adg, mwg, _std)]
55 /// 54 ///
56 #[doc = stdlinks!(3 pam_getenv)] 55 #[doc = stdlinks!(3 pam_getenv)]
57 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_getenv")] 56 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_getenv")]
58 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_getenv")] 57 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_getenv")]
59 fn environ(&self) -> impl EnvironMap; 58 fn environ(&self) -> impl EnvironMap;
60 59
61 /// A writable map of the environment to set for the logged-in user. 60 /// A writable map of the environment to set for the logged-in user.
62 /// 61 ///
63 /// # References 62 /// # References
64 ///
65 #[doc = linklist!(pam_putenv: adg, mwg, _std)] 63 #[doc = linklist!(pam_putenv: adg, mwg, _std)]
66 /// 64 ///
67 #[doc = stdlinks!(3 pam_putenv)] 65 #[doc = stdlinks!(3 pam_putenv)]
68 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_putenv")] 66 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_putenv")]
69 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_putenv")] 67 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_putenv")]
74 /// Certain Items should not be accessed by a PAM application; 72 /// Certain Items should not be accessed by a PAM application;
75 /// those are available directly on [`ModuleClient`] for use 73 /// those are available directly on [`ModuleClient`] for use
76 /// by PAM modules only. 74 /// by PAM modules only.
77 /// 75 ///
78 /// # References 76 /// # References
79 ///
80 #[doc = linklist!(pam_get_item: mwg, adg, _std)] 77 #[doc = linklist!(pam_get_item: mwg, adg, _std)]
81 /// 78 ///
82 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")] 79 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
83 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")] 80 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
84 #[doc = stdlinks!(3 pam_get_item)] 81 #[doc = stdlinks!(3 pam_get_item)]
85 fn items(&self) -> impl Items; 82 fn items(&self) -> impl Items;
86 83
87 /// Read-write access to PAM Items. 84 /// Read-write access to PAM Items.
88 /// 85 ///
89 /// # References 86 /// # References
90 ///
91 #[doc = linklist!(pam_set_item: mwg, adg, _std)] 87 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
92 /// 88 ///
93 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")] 89 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
94 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")] 90 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
95 #[doc = stdlinks!(3 pam_set_item)] 91 #[doc = stdlinks!(3 pam_set_item)]
163 /// [`pam_authtok_get` module][pam_authtok_get]. On Sun, this function 159 /// [`pam_authtok_get` module][pam_authtok_get]. On Sun, this function
164 /// is exactly equivalent to [`Self::authtok_item`], in that it only 160 /// is exactly equivalent to [`Self::authtok_item`], in that it only
165 /// retrieves the existing item. 161 /// retrieves the existing item.
166 /// 162 ///
167 /// # References 163 /// # References
168 ///
169 #[doc = linklist!(pam_get_authtok: man7, manbsd)] 164 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
170 /// 165 ///
171 /// # Example 166 /// # Example
172 /// 167 ///
173 /// ```no_run 168 /// ```no_run
188 /// Retrieves the user's old authentication token when changing passwords. 183 /// Retrieves the user's old authentication token when changing passwords.
189 /// 184 ///
190 /// This should only be used by a *password-change* module. 185 /// This should only be used by a *password-change* module.
191 /// 186 ///
192 /// # References 187 /// # References
193 ///
194 #[doc = linklist!(pam_get_authtok: man7, manbsd)] 188 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
195 /// 189 ///
196 /// # Example 190 /// # Example
197 /// 191 ///
198 /// ```no_run 192 /// ```no_run
203 /// // Get the user's password using a custom prompt. 197 /// // Get the user's password using a custom prompt.
204 /// let pass = handle.old_authtok(Some("Reveal your secrets!".as_ref()))?; 198 /// let pass = handle.old_authtok(Some("Reveal your secrets!".as_ref()))?;
205 /// Ok(()) 199 /// Ok(())
206 /// # } 200 /// # }
207 /// ``` 201 /// ```
208 ///
209 #[doc = stdlinks!(3 pam_get_authtok)] 202 #[doc = stdlinks!(3 pam_get_authtok)]
210 fn old_authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>; 203 fn old_authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
211 204
212 /// Gets an item of module-specific data stored over the transaction. 205 /// Gets an item of module-specific data stored over the transaction.
213 /// 206 ///
227 /// let nothing_data: Option<&PathBuf> = client.get_module_data("this does not exist"); 220 /// let nothing_data: Option<&PathBuf> = client.get_module_data("this does not exist");
228 /// # } 221 /// # }
229 /// ``` 222 /// ```
230 /// 223 ///
231 /// # References 224 /// # References
232 ///
233 #[doc = linklist!(pam_get_data: mwg, _std)] 225 #[doc = linklist!(pam_get_data: mwg, _std)]
234 /// 226 ///
235 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_data")] 227 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_data")]
236 #[doc = stdlinks!(3 pam_get_data)] 228 #[doc = stdlinks!(3 pam_get_data)]
237 229
280 /// // Later, in a pam_session_start call: 272 /// // Later, in a pam_session_start call:
281 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> { 273 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
282 /// match client.get_module_data::<u64>("TOKEN_ID") { 274 /// match client.get_module_data::<u64>("TOKEN_ID") {
283 /// Some(&tid) => { 275 /// Some(&tid) => {
284 /// // This will execute and tid will be 0x0fa1afe10000beef. 276 /// // This will execute and tid will be 0x0fa1afe10000beef.
285 /// }, 277 /// }
286 /// None => { /* This will not execute. */ }, 278 /// None => { /* This will not execute. */ }
287 /// } 279 /// }
288 /// Ok(()) 280 /// Ok(())
289 /// } 281 /// }
290 /// ``` 282 /// ```
291 /// 283 ///
303 /// fn in_pam_module_b(client: &mut impl ModuleClient) -> Result<()> { 295 /// fn in_pam_module_b(client: &mut impl ModuleClient) -> Result<()> {
304 /// match client.get_module_data::<String>("value") { 296 /// match client.get_module_data::<String>("value") {
305 /// Some(value) => { 297 /// Some(value) => {
306 /// // This will match, because pam_module_a's data 298 /// // This will match, because pam_module_a's data
307 /// // is completely unrelated to pam_module_b's data. 299 /// // is completely unrelated to pam_module_b's data.
308 /// }, 300 /// }
309 /// None => { 301 /// None => {
310 /// // This branch will execute. 302 /// // This branch will execute.
311 /// }, 303 /// }
312 /// } 304 /// }
313 /// // ... 305 /// // ...
314 /// # Ok(()) 306 /// # Ok(())
315 /// } 307 /// }
316 /// ``` 308 /// ```
347 /// 339 ///
348 /// While LibPAM offers a way to customize the action taken on cleanup, 340 /// While LibPAM offers a way to customize the action taken on cleanup,
349 /// we do not (yet) offer this. 341 /// we do not (yet) offer this.
350 /// 342 ///
351 /// # References 343 /// # References
352 ///
353 #[doc = linklist!(pam_set_data: mwg, _std)] 344 #[doc = linklist!(pam_set_data: mwg, _std)]
354 /// 345 ///
355 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_data")] 346 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_data")]
356 #[doc = stdlinks!(3 pam_set_data)] 347 #[doc = stdlinks!(3 pam_set_data)]
357 fn set_module_data<T: 'static>(&mut self, key: &str, data: T) -> Result<()>; 348 fn set_module_data<T: 'static>(&mut self, key: &str, data: T) -> Result<()>;