Mercurial > crates > nonstick

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

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
147:4d7333337569 148:4b3a5095f68c
1 //! `libpam-sys` provides low-level access to `libpam`. 1 //! `libpam-sys` provides low-level access to LibPAM.
2 //! 2 //!
3 //! Everything in here is directly as exported from the `libpam` library or 3 //! Everything in here is directly as exported from the LibPAM library or
4 //! its header files, with limited exceptions: 4 //! its header files, with two exceptions:
5 //! 5 //!
6 //! - The [`pam_impl`] submodule (and the [`pam_impl_name!`] macro) contains 6 //! - The [`pam_impl`] submodule (and the associated [`pam_impl_name!`] macro),
7 //! tools for detecting the current PAM library. 7 //! which can be used to detect the current PAM implementation.
8 //! - [`AppData`] is an opaque pointer newtype. 8 //! - The [`aliases`] submodule, which contains convenient aliases
9 //! - [`ConversationCallback`] and [`CleanupCallback`] are aliases for 9 //! for callback types used in libpam, so you don't have to type
10 //! what are otherwise anonymous function types. 10 //! `unsafe extern "C" fn(this is so long)` all the time.
11 //! 11 //!
12 #![doc = concat!("This documentation was built for the **", pam_impl_name!(), "** implementation.")] 12 #![doc = concat!("This documentation was built for the **", pam_impl_name!(), "** implementation.")]
13 //! 13 //!
14 //! You can override this **at build time** by setting the `LIBPAMSYS_IMPL` 14 //! You can override this **at build time** by setting the `LIBPAMSYS_IMPL`
15 //! environment variable to one of the values of the [`pam_impl::PamImpl`] enum. 15 //! environment variable to one of the values of the [`pam_impl::PamImpl`] enum.
16 //! 16 //! For more information about configuration, see the documentation of
17 //! For more information about configuration, see [the README](https://crates.io/crate/libpam-sys). 17 //! [`libpam-sys-consts`](https://crates.io/crates/libpam-sys-consts).
18 #![allow(non_camel_case_types)] 18 #![allow(non_camel_case_types)]
19 #![allow(unused_imports)] 19 #![allow(unused_imports)]
20 20
21 pub mod aliases;
21 #[doc(inline)] 22 #[doc(inline)]
22 pub use libpam_sys_helpers::constants::*; 23 pub use libpam_sys_consts::constants::*;
23 #[doc(inline)] 24 #[doc(inline)]
24 pub use libpam_sys_helpers::{pam_impl, pam_impl_name}; 25 pub use libpam_sys_consts::{pam_impl, pam_impl_name};
25 use std::ffi::{c_char, c_int, c_uint, c_void}; 26 use std::ffi::{c_char, c_int, c_uint, c_void};
26 use std::fmt; 27 use std::fmt;
27 use std::marker::{PhantomData, PhantomPinned}; 28 use std::marker::{PhantomData, PhantomPinned};
28 29
29 /// A marker struct to make whatever it's in `!Sync`, `!Send`, and `!Unpin`.
30 #[derive(Default, PartialOrd, PartialEq, Ord, Eq)]
31 #[repr(C)]
32 struct ExtremelyUnsafe {
33 _value: (),
34 _marker: PhantomData<(PhantomPinned, *mut c_void)>,
35 }
36
37 impl fmt::Debug for ExtremelyUnsafe {
38 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39 write!(f, "ExtremelyUnsafe({self:p})")
40 }
41 }
42
43 /// An opaque structure that PAM uses to communicate. 30 /// An opaque structure that PAM uses to communicate.
44 /// 31 ///
45 /// This is only ever returned in pointer form and cannot be constructed. 32 /// This is only ever returned in pointer form and cannot be constructed.
46 #[repr(C)] 33 #[repr(C)]
47 pub struct pam_handle(ExtremelyUnsafe); 34 pub struct pam_handle {
35 _value: (),
36 _marker: PhantomData<(PhantomPinned, *mut c_void)>,
37 }
48 38
49 impl fmt::Debug for pam_handle { 39 impl fmt::Debug for pam_handle {
50 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 40 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51 write!(f, "pam_handle({self:p}") 41 write!(f, "pam_handle({self:p}")
52 } 42 }
53 } 43 }
54
55 /// An opaque structure that is passed through PAM in a conversation.
56 #[repr(C)]
57 pub struct AppData(ExtremelyUnsafe);
58
59 impl fmt::Debug for AppData {
60 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61 write!(f, "AppData({self:p}")
62 }
63 }
64
65 /// Just an alias for the type of [`pam_conv::conv`].
66 ///
67 /// For important details about the format of `messages`,
68 /// see [`libpam_sys_helpers::memory::PtrPtrVec`].
69 ///
70 /// ```no_run
71 /// # use libpam_sys::{ConversationCallback, pam_conv};
72 /// fn convo() -> ConversationCallback {
73 /// // ...
74 /// # unimplemented!()
75 /// }
76 /// let conv = pam_conv{conv: convo(), appdata_ptr: std::ptr::null_mut()};
77 /// ```
78 pub type ConversationCallback = unsafe extern "C" fn(
79 num_msg: c_int,
80 msg: *const *const pam_message,
81 resp: *mut *mut pam_response,
82 appdata: *mut AppData,
83 ) -> c_int;
84
85 /// Alias for the callback to [`pam_set_data`].
86 ///
87 /// ```no_run
88 /// # use std::ffi::CString;
89 /// use libpam_sys::{CleanupCallback, pam_set_data};
90 /// # use libpam_sys::pam_handle;
91 /// # let handle: *mut pam_handle = std::ptr::null_mut();
92 /// # let mut my_data = 100;
93 /// # let data_ptr = &mut my_data as *mut i32;
94 /// fn cleanup() -> CleanupCallback {
95 /// // ...
96 /// # unimplemented!()
97 /// }
98 /// let name = CString::new("name").unwrap();
99 /// unsafe {
100 /// pam_set_data(handle, name.as_ptr().cast_mut(), data_ptr.cast(), cleanup());
101 /// }
102 /// ```
103 pub type CleanupCallback =
104 unsafe extern "C" fn(pamh: *mut pam_handle, data: *mut c_void, pam_end_status: c_int);
105 44
106 /// Used by PAM to communicate between the module and the application. 45 /// Used by PAM to communicate between the module and the application.
107 #[repr(C)] 46 #[repr(C)]
108 pub struct pam_conv { 47 pub struct pam_conv {
109 pub conv: unsafe extern "C" fn( 48 pub conv: unsafe extern "C" fn(
110 num_msg: c_int, 49 num_msg: c_int,
111 msg: *const *const pam_message, 50 msg: *const *const pam_message,
112 resp: *mut *mut pam_response, 51 resp: *mut *mut pam_response,
113 appdata: *mut AppData, 52 appdata: *mut c_void,
114 ) -> c_int, 53 ) -> c_int,
115 pub appdata_ptr: *mut AppData, 54 pub appdata_ptr: *mut c_void,
116 } 55 }
117 56
118 /// A message sent into a PAM conversation. 57 /// A message sent into a PAM conversation.
119 #[repr(C)] 58 #[repr(C)]
120 pub struct pam_message { 59 pub struct pam_message {