1 //! Load and unload kernel modules.
2 //!
3 //! For more details see
4
5 use std::ffi::CStr;
6 use std::os::unix::io::AsRawFd;
7
8 use crate::errno::Errno;
9 use crate::Result;
10
11 /// Loads a kernel module from a buffer.
12 ///
13 /// It loads an ELF image into kernel space,
14 /// performs any necessary symbol relocations,
15 /// initializes module parameters to values provided by the caller,
16 /// and then runs the module's init function.
17 ///
18 /// This function requires `CAP_SYS_MODULE` privilege.
19 ///
20 /// The `module_image` argument points to a buffer containing the binary image
21 /// to be loaded. The buffer should contain a valid ELF image
22 /// built for the running kernel.
23 ///
24 /// The `param_values` argument is a string containing space-delimited specifications
25 /// of the values for module parameters.
26 /// Each of the parameter specifications has the form:
27 ///
28 /// `name[=value[,value...]]`
29 ///
30 /// # Example
31 ///
32 /// ```no_run
33 /// use std::fs::File;
34 /// use std::io::Read;
35 /// use std::ffi::CString;
36 /// use nix::kmod::init_module;
37 ///
38 /// let mut f = File::open("mykernel.ko").unwrap();
39 /// let mut contents: Vec<u8> = Vec::new();
40 /// f.read_to_end(&mut contents).unwrap();
41 /// init_module(&mut contents, &CString::new("who=Rust when=Now,12").unwrap()).unwrap();
42 /// ```
43 ///
44 /// See [`man init_module(2)`](https://man7.org/linux/man-pages/man2/init_module.2.html) for more information.
init_module(module_image: &[u8], param_values: &CStr) -> Result<()>45 pub fn init_module(module_image: &[u8], param_values: &CStr) -> Result<()> {
46 let res = unsafe {
47 libc::syscall(
48 libc::SYS_init_module,
49 module_image.as_ptr(),
50 module_image.len(),
51 param_values.as_ptr(),
52 )
53 };
54
55 Errno::result(res).map(drop)
56 }
57
58 libc_bitflags!(
59 /// Flags used by the `finit_module` function.
60 pub struct ModuleInitFlags: libc::c_uint {
61 /// Ignore symbol version hashes.
62 MODULE_INIT_IGNORE_MODVERSIONS;
63 /// Ignore kernel version magic.
64 MODULE_INIT_IGNORE_VERMAGIC;
65 }
66 );
67
68 /// Loads a kernel module from a given file descriptor.
69 ///
70 /// # Example
71 ///
72 /// ```no_run
73 /// use std::fs::File;
74 /// use std::ffi::CString;
75 /// use nix::kmod::{finit_module, ModuleInitFlags};
76 ///
77 /// let f = File::open("mymod.ko").unwrap();
78 /// finit_module(&f, &CString::new("").unwrap(), ModuleInitFlags::empty()).unwrap();
79 /// ```
80 ///
81 /// See [`man init_module(2)`](https://man7.org/linux/man-pages/man2/init_module.2.html) for more information.
finit_module<T: AsRawFd>(fd: &T, param_values: &CStr, flags: ModuleInitFlags) -> Result<()>82 pub fn finit_module<T: AsRawFd>(fd: &T, param_values: &CStr, flags: ModuleInitFlags) -> Result<()> {
83 let res = unsafe {
84 libc::syscall(
85 libc::SYS_finit_module,
86 fd.as_raw_fd(),
87 param_values.as_ptr(),
88 flags.bits(),
89 )
90 };
91
92 Errno::result(res).map(drop)
93 }
94
95 libc_bitflags!(
96 /// Flags used by `delete_module`.
97 ///
98 /// See [`man delete_module(2)`](https://man7.org/linux/man-pages/man2/delete_module.2.html)
99 /// for a detailed description how these flags work.
100 pub struct DeleteModuleFlags: libc::c_int {
101 O_NONBLOCK;
102 O_TRUNC;
103 }
104 );
105
106 /// Unloads the kernel module with the given name.
107 ///
108 /// # Example
109 ///
110 /// ```no_run
111 /// use std::ffi::CString;
112 /// use nix::kmod::{delete_module, DeleteModuleFlags};
113 ///
114 /// delete_module(&CString::new("mymod").unwrap(), DeleteModuleFlags::O_NONBLOCK).unwrap();
115 /// ```
116 ///
117 /// See [`man delete_module(2)`](https://man7.org/linux/man-pages/man2/delete_module.2.html) for more information.
delete_module(name: &CStr, flags: DeleteModuleFlags) -> Result<()>118 pub fn delete_module(name: &CStr, flags: DeleteModuleFlags) -> Result<()> {
119 let res = unsafe { libc::syscall(libc::SYS_delete_module, name.as_ptr(), flags.bits()) };
120
121 Errno::result(res).map(drop)
122 }
123