3 releases
Uses old Rust 2015
0.4.2 | Dec 19, 2023 |
---|---|
0.4.1 | Jun 7, 2022 |
0.4.0 | Nov 15, 2021 |
#15 in Operating systems
729,161 downloads per month
Used in 1,546 crates
(43 directly)
88KB
2K
SLoC
mach2
A Rust interface to the user-space API of the Mach 3.0 kernel exposed in
/usr/include/mach
that underlies macOS and is linked via libSystem
(and
libsystem_kernel
).
This library does not expose the kernel-space API of the Mach 3.0 kernel
exposed in
SDK/System/Library/Frameworks/Kernel.framework/Versions/A/Headers/mach
.
That is, if you are writing a kernel-resident device drivers or some other kernel extensions you have to use something else. The user-space kernel API is often API-incompatible with the kernel space one, and even in the cases where they match, they are sometimes ABI incompatible such that using this library would have undefined behavior.
Usage
Add the following to your Cargo.toml
to conditionally include mach on those
platforms that support it.
[target.'cfg(any(target_os = "macos", target_os = "ios"))'.dependencies.mach]
version = "0.4"
Available crate feature:
- unstable (disabled by default): Exposes newly changed APIs. Enabling this may bring breaking changes (see the breaking change policy).
Breaking change policy
We do the following steps when an item is changed/removed on latest toolchain:
- Deprecate an existing one
- Declare a new one under the
unstable
feature - After a month or more since releasing a new version that contains that change, remove/change an older one
For instance, if const FOO
value is changed from 3
to 4
,
we expose the newer one, i.e. 4
, under unstable
first.
So the unstable
users should notice the change on the first release since deprecating.
After a month or more, all the users should notice it.
Examples
Examples can be found in the examples directory of this repository.
Since examples/dump_process_registers.rs
makes use of the task_for_pid()
function, which requires elevated privileges, it is necessary to disable System Integrity Protection (SIP) and to be part of the admin
or _developer
group in order to run the example. However, do note that disabling SIP is in no way encouraged, and should only be done for development/debugging purposes.
- Reboot macOS in recovery mode.
- Click on
Options
. - Log in to your user.
- In the menu click on
Utilities
and thenTerminal
. - In the terminal type the following command to disable SIP:
csrutil disable
(csrutil enable
to re-enable SIP). - Reboot your machine.
To run the example, build it as follows:
cargo b --example dump_process_registers
Then run it using sudo
:
sudo ./target/debug/examples/dump_process_registers
Platform support
The following table describes the current CI set-up:
Target | Min. Rust | XCode | build | ctest | run |
---|---|---|---|---|---|
x86_64-apple-darwin |
1.33.0 | 10.3.0 - 13.1.0 | ✓ | ✓ | ✓ |
aarch64-apple-darwin |
nightly | 13.1.0 | ✓ | - | - |
aarch64-apple-ios |
nightly | 13.1.0 | ✓ | - | - |
aarch64-apple-ios-sim |
nightly | 13.1.0 | ✓ | - | - |
x86_64-apple-ios |
nightly | 13.1.0 | ✓ | - | - |
License
This project is licensed under either of
- A 2-clause BSD License (LICENSE-BSD), or
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in mach
by you, as defined in the Apache-2.0 license, shall be
triple licensed as above, without any additional terms or conditions.
To locally test the library, run:
TARGET=x86_64-apple-darwin RUST_VERSION=nightly ./ci/run.sh
where you can replace the TARGET
and RUST_VERSION
with the target you
want to test (e.g. aarch64-apple-darwin
) and the Rust version you want to use for
the tests (e.g. stable
, 1.33.0
, etc.).