Mercurial > crates > nonstick

comparison src/lib.rs @ 184:42f747774d94

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Really get documentation stuff squared away. Expand READMEs and polish off module documentation.
author Paul Fisher <paul@pfish.zone>
date Thu, 31 Jul 2025 14:36:50 -0400
parents 4f46681b3f54
children b2456d274576
comparison
equal deleted inserted replaced
183:4f46681b3f54 184:42f747774d94
137 //! nonstick detects which implementation it should use for the current target. 137 //! nonstick detects which implementation it should use for the current target.
138 //! If you need to choose a different implementation, set the `LIBPAMSYS_IMPL` 138 //! If you need to choose a different implementation, set the `LIBPAMSYS_IMPL`
139 //! environment variable at build time. See the [`libpam_sys`] documentation. 139 //! environment variable at build time. See the [`libpam_sys`] documentation.
140 #![doc = concat!("This documentation was built for **", pam_impl_name!(), "**.")] 140 #![doc = concat!("This documentation was built for **", pam_impl_name!(), "**.")]
141 //! 141 //!
142 //! # Cargo features
143 //!
144 //! This crate provides the following Cargo features:
145 //!
146 //! - **link** (enabled by default): Actually link against PAM,
147 //! rather than just providing an abstract PAM interface.
148 //! Enabling this will fail if extensions incompatible with the
149 //! PAM implementation you're linking against are also enabled.
150 //! - Extensions beyond the PAM specification provided by various PAM
151 //! implementations:
152 //! - **basic-ext**: Enable extensions provided by both Linux-PAM and OpenPAM.
153 //! This is limited to a few return enums.
154 //! - **linux-pam-ext** (includes basic-ext): Enable extensions provided by
155 //! Linux-PAM. This includes enum values and the ability to send
156 //! binary messages between the PAM module and the application.
157 //! - **openpam-ext** (includes basic-ext): Enable extensions provided by
158 //! OpenPAM. This includes enum values.
159 //! - **sun-ext**: Enable extensions provided by Sun PAM.
160 //! This includes enum values.
161 //!
162 //! # Design
163 //!
164 //! This library consists of two parts:
165 //!
166 //! - The generic PAM interface, a set of traits describing the behavior of PAM
167 //! and the API we export. It is independent of the PAM library itself and
168 //! could be implemented by any crate to provide PAM-like services.
169 //! This is primarily intended to allow a developer to test their PAM modules
170 //! and applications by writing mock implementations to verify their
171 //! application (or module) code's interactions with PAM itself.
172 //!
173 //! - The bindings to LibPAM itself. This part is included only when **link**
174 //! is enabled. These live in the `libpam` submodule (with a few exceptions
175 //! for constant-related code).
176 //!
142 //! # References 177 //! # References
178 //!
179 //! These documents were used when authoring this library and will probably be
180 //! of value if you want to implement a PAM module or a PAM application.
143 //! 181 //!
144 //! - The Linux-PAM guides provide information for a variety of audiences. 182 //! - The Linux-PAM guides provide information for a variety of audiences.
145 //! While some of it is specific to Linux-PAM, much of it applies to other 183 //! While some of it is specific to Linux-PAM, much of it applies to other
146 //! PAM implementations: 184 //! PAM implementations:
147 //! - [Application Developers' Guide][adg] 185 //! - [Application Developers' Guide][adg]
154 //! - PAM framework man page for system administrators: 192 //! - PAM framework man page for system administrators:
155 //! - [Linux-PAM admin documentation][man7pam8] 193 //! - [Linux-PAM admin documentation][man7pam8]
156 //! - [OpenPAM admin documentation][bsdpam8] 194 //! - [OpenPAM admin documentation][bsdpam8]
157 //! - [Illumos pam.conf documentation][sunpam5] 195 //! - [Illumos pam.conf documentation][sunpam5]
158 //! - [The original PAM specification][spec] (mostly of historical interest) 196 //! - [The original PAM specification][spec] (mostly of historical interest)
197 //! - [Cooking spray](https://en.wikipedia.org/wiki/Cooking_spray)
159 #![doc = ""] 198 #![doc = ""]
160 #![doc = crate::_doc::man7!(man7pam8: 8 pam)] 199 #![doc = _doc::man7!(man7pam8: 8 pam)]
161 #![doc = crate::_doc::manbsd!(bsdpam8: 8 pam)] 200 #![doc = _doc::manbsd!(bsdpam8: 8 pam)]
162 #![doc = crate::_doc::mansun!(sunpam5: 5 "pam.conf")] 201 #![doc = _doc::mansun!(sunpam5: 5 "pam.conf")]
163 #![doc = crate::_doc::stdlinks!(3 pam)] 202 #![doc = _doc::stdlinks!(3 pam)]
164 #![doc = crate::_doc::guide!(adg: "Linux-PAM_ADG.html")] 203 #![doc = _doc::guide!(adg: "Linux-PAM_ADG.html")]
165 #![doc = crate::_doc::guide!(mwg: "Linux-PAM_MWG.html")] 204 #![doc = _doc::guide!(mwg: "Linux-PAM_MWG.html")]
166 #![doc = crate::_doc::guide!(sag: "Linux-PAM_SAG.html")] 205 #![doc = _doc::guide!(sag: "Linux-PAM_SAG.html")]
167 #![doc = crate::_doc::xsso!(spec: "toc.htm")] 206 #![doc = _doc::xsso!(spec: "toc.htm")]
168 207
169 #[cfg(feature = "link")] 208 #[cfg(feature = "link")]
170 mod _compat_checker { 209 mod _compat_checker {
171 macro_rules! feature_check { 210 macro_rules! feature_check {
172 ($feature:literal, pam_impl = ($($pimpl:literal),*)) => { 211 ($feature:literal, pam_impl = ($($pimpl:literal),*)) => {