annotate libpam-sys/libpam-sys-helpers/src/pam_impl.rs @ 141:a508a69c068a

Remove a lot of Results from functions. Many functions are documented to only return failing Results when given improper inputs or when there is a memory allocation failure (which can be verified by looking at the source). In cases where we know our input is correct, we don't need to check for memory allocation errors for the same reason that Rust doesn't do so when you, e.g., create a new Vec.
author Paul Fisher <paul@pfish.zone>
date Sat, 05 Jul 2025 17:16:56 -0400
parents efbc235f01d3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
1 // This file is include!d directly by `../build.rs`, so its doc comment
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
2 // is found in lib.rs.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
3
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4 /// An enum that knows its own values.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5 macro_rules! self_aware_enum {
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
6 (
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
7 $(#[$enumeta:meta])*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
8 $viz:vis enum $name:ident {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
9 $(
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
10 $(#[$itemeta:meta])*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
11 $item:ident,
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
12 )*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
13 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
14 ) => {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
15 $(#[$enumeta])*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
16 $viz enum $name {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
17 $(
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
18 $(#[$itemeta])*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
19 $item,
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
20 )*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
21 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
22
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
23 // The implementations in this block are private for now
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
24 // to avoid putting a contract into the public API.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
25 #[allow(dead_code)]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
26 impl $name {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
27 /// Iterator over the items in the enum. For internal use.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
28 fn items() -> Vec<Self> {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
29 vec![$(Self::$item),*]
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
32 /// Attempts to parse the enum from the string. For internal use.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
33 fn try_from(value: &str) -> Result<Self, String> {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
34 match value {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
35 $(stringify!($item) => Ok(Self::$item),)*
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
36 _ => Err(value.into()),
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 }
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
39 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
40 };
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
41 }
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 self_aware_enum! {
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 /// The PAM implementations supported by `libpam-sys`.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 #[cfg_attr(pam_impl, non_exhaustive)]
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 pub enum PamImpl {
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48 /// [Linux-PAM] is provided by most Linux distributions.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 /// [Linux-PAM]: https://github.com/linux-pam/linux-pam
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51 LinuxPam,
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 /// [OpenPAM] is used by most BSDs, including Mac OS X.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54 /// [OpenPAM]: https://git.des.dev/OpenPAM/OpenPAM
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 OpenPam,
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56 /// Illumos and Solaris use a derivative of [Sun's implementation][sun].
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
58 /// [sun]: https://code.illumos.org/plugins/gitiles/illumos-gate/+/refs/heads/master/usr/src/lib/libpam
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
59 Sun,
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 /// Only the functionality and constants in [the PAM spec].
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
61 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62 /// [the PAM spec]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63 XSso,
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64 }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
65 }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
66
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
67 // This generated file contains:
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
68 // - pam_impl_name!
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
69 // - PamImpl::CURRENT
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 #[cfg(pam_impl)]
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
71 include!(concat!(env!("OUT_DIR"), "/pam_impl_const.rs"));
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
72
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
73 #[allow(clippy::needless_doctest_main)]
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
74 /// Generates `cargo` directives for build scripts to enable `cfg(pam_impl)`.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
75 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
76 /// Print this in your `build.rs` script to be able to use the custom `pam_impl`
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
77 /// configuration directive.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
78 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
79 /// ```
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
80 /// // build.rs
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
81 /// use libpam_sys_helpers::pam_impl;
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
82 /// fn main() {
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
83 /// pam_impl::enable_pam_impl_cfg();
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
84 ///
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
85 /// // Whatever other stuff you do in your build.rs.
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
86 /// }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
87 /// ```
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
88 #[cfg(pam_impl)]
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
89 pub fn enable_pam_impl_cfg() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
90 println!("{}", pam_impl_cfg_string())
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
91 }
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
92
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
93 /// Generates the `cargo:` directives to print in build scripts.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
94 #[cfg(pam_impl)]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
95 pub fn pam_impl_cfg_string() -> String {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
96 generate_cfg(pam_impl_name!())
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
97 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
98
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
99 fn generate_cfg(name: &str) -> String {
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
100 let impls: Vec<_> = PamImpl::items()
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
101 .into_iter()
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
102 .map(|i| format!(r#""{i:?}""#))
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
103 .collect();
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
104 format!(
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
105 "\
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
106 cargo:rustc-check-cfg=cfg(pam_impl)
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
107 cargo:rustc-check-cfg=cfg(pam_impl, values({impls}))
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
108 cargo:rustc-cfg=pam_impl
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 134
diff changeset
109 cargo:rustc-cfg=pam_impl={name:?}
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
110 ",
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
111 impls = impls.join(",")
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
112 )
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
113 }