diff libpam-sys/src/lib.rs @ 148:4b3a5095f68c

Move libpam-sys helpers into their own library. - Renames libpam-sys-helpers to libpam-sys-consts. - Moves libpam-sys-helpers::helpers into libpam-sys-helpers, which moves them completely out of libpam-sys's dependency chain. - Moves the aliases from libpam-sys into libpam-sys::aliases.
author Paul Fisher <paul@pfish.zone>
date Mon, 07 Jul 2025 12:11:43 -0400
parents 999bf07efbcb
children 3036f2e6a022
line wrap: on
line diff
--- a/libpam-sys/src/lib.rs	Sun Jul 06 19:23:02 2025 -0400
+++ b/libpam-sys/src/lib.rs	Mon Jul 07 12:11:43 2025 -0400
@@ -1,50 +1,40 @@
-//! `libpam-sys` provides low-level access to `libpam`.
+//! `libpam-sys` provides low-level access to LibPAM.
 //!
-//! Everything in here is directly as exported from the `libpam` library or
-//! its header files, with limited exceptions:
+//! Everything in here is directly as exported from the LibPAM library or
+//! its header files, with two exceptions:
 //!
-//! - The [`pam_impl`] submodule (and the [`pam_impl_name!`] macro) contains
-//!   tools for detecting the current PAM library.
-//! - [`AppData`] is an opaque pointer newtype.
-//! - [`ConversationCallback`] and [`CleanupCallback`] are aliases for
-//!   what are otherwise anonymous function types.
+//! - The [`pam_impl`] submodule (and the associated [`pam_impl_name!`] macro),
+//!   which can be used to detect the current PAM implementation.
+//! - The [`aliases`] submodule, which contains convenient aliases
+//!   for callback types used in libpam, so you don't have to type
+//!   `unsafe extern "C" fn(this is so long)` all the time.
 //!
 #![doc = concat!("This documentation was built for the **", pam_impl_name!(), "** implementation.")]
 //!
 //! You can override this **at build time** by setting the `LIBPAMSYS_IMPL`
 //! environment variable to one of the values of the [`pam_impl::PamImpl`] enum.
-//!
-//! For more information about configuration, see [the README](https://crates.io/crate/libpam-sys).
+//! For more information about configuration, see the documentation of
+//! [`libpam-sys-consts`](https://crates.io/crates/libpam-sys-consts).
 #![allow(non_camel_case_types)]
 #![allow(unused_imports)]
 
+pub mod aliases;
 #[doc(inline)]
-pub use libpam_sys_helpers::constants::*;
+pub use libpam_sys_consts::constants::*;
 #[doc(inline)]
-pub use libpam_sys_helpers::{pam_impl, pam_impl_name};
+pub use libpam_sys_consts::{pam_impl, pam_impl_name};
 use std::ffi::{c_char, c_int, c_uint, c_void};
 use std::fmt;
 use std::marker::{PhantomData, PhantomPinned};
 
-/// A marker struct to make whatever it's in `!Sync`, `!Send`, and `!Unpin`.
-#[derive(Default, PartialOrd, PartialEq, Ord, Eq)]
-#[repr(C)]
-struct ExtremelyUnsafe {
-    _value: (),
-    _marker: PhantomData<(PhantomPinned, *mut c_void)>,
-}
-
-impl fmt::Debug for ExtremelyUnsafe {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "ExtremelyUnsafe({self:p})")
-    }
-}
-
 /// An opaque structure that PAM uses to communicate.
 ///
 /// This is only ever returned in pointer form and cannot be constructed.
 #[repr(C)]
-pub struct pam_handle(ExtremelyUnsafe);
+pub struct pam_handle {
+    _value: (),
+    _marker: PhantomData<(PhantomPinned, *mut c_void)>,
+}
 
 impl fmt::Debug for pam_handle {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -52,57 +42,6 @@
     }
 }
 
-/// An opaque structure that is passed through PAM in a conversation.
-#[repr(C)]
-pub struct AppData(ExtremelyUnsafe);
-
-impl fmt::Debug for AppData {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "AppData({self:p}")
-    }
-}
-
-/// Just an alias for the type of [`pam_conv::conv`].
-///
-/// For important details about the format of `messages`,
-/// see [`libpam_sys_helpers::memory::PtrPtrVec`].
-///
-/// ```no_run
-/// # use libpam_sys::{ConversationCallback, pam_conv};
-/// fn convo() -> ConversationCallback {
-///     // ...
-/// #    unimplemented!()
-/// }
-/// let conv = pam_conv{conv: convo(), appdata_ptr: std::ptr::null_mut()};
-/// ```
-pub type ConversationCallback = unsafe extern "C" fn(
-    num_msg: c_int,
-    msg: *const *const pam_message,
-    resp: *mut *mut pam_response,
-    appdata: *mut AppData,
-) -> c_int;
-
-/// Alias for the callback to [`pam_set_data`].
-///
-/// ```no_run
-/// # use std::ffi::CString;
-/// use libpam_sys::{CleanupCallback, pam_set_data};
-/// # use libpam_sys::pam_handle;
-/// # let handle: *mut pam_handle = std::ptr::null_mut();
-/// # let mut my_data = 100;
-/// # let data_ptr = &mut my_data as *mut i32;
-/// fn cleanup() -> CleanupCallback {
-///     // ...
-/// #    unimplemented!()
-/// }
-/// let name = CString::new("name").unwrap();
-/// unsafe {
-///     pam_set_data(handle, name.as_ptr().cast_mut(), data_ptr.cast(), cleanup());
-/// }
-/// ```
-pub type CleanupCallback =
-    unsafe extern "C" fn(pamh: *mut pam_handle, data: *mut c_void, pam_end_status: c_int);
-
 /// Used by PAM to communicate between the module and the application.
 #[repr(C)]
 pub struct pam_conv {
@@ -110,9 +49,9 @@
         num_msg: c_int,
         msg: *const *const pam_message,
         resp: *mut *mut pam_response,
-        appdata: *mut AppData,
+        appdata: *mut c_void,
     ) -> c_int,
-    pub appdata_ptr: *mut AppData,
+    pub appdata_ptr: *mut c_void,
 }
 
 /// A message sent into a PAM conversation.