Expand description
§mach-sys: forked from original “mach”, and merge from “mach2” & “machx”.
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.
(notes from machx developers:)
1. due to the lack of maintenance of `mach2` and `mach`, a lot of APIs are missing, so I maintain this version for my own use.
2. via bindgen as well as manual fixes.§Usage
Add the following to your Cargo.toml to conditionally include mach on those
platforms that support it.
[target.'cfg(target_vendor="apple")'.dependencies]
# use alias for migration from exists project:
mach = { package = "mach-sys", version = "0.5" }
# or without alias:
mach-sys = "0.5"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:
-
Flagging an existing one as Deprecated.
-
Declare a new one (by default).
-
Forever kept older one.
-
if two items have equivalents value, then type alias to new one, or internal function calling new one.
-
otherwise, if two items have different value or behavior, then both will exists together.
-
or, in cases, if the older one is really sucks, then After a month or more since releasing a new version that contains that remove an older one.
For instance (equivalent), if function FUNC will changes it’s return type from u32 to u64, a new function will be created, then older function just call it and convert it’s return type (u64 as u32). in most of cases, no more changes will be taken, and both of these will be kept forever.
For instance (non-equivalent), if const FOO value is changed from 3 to 4,
we expose the newer one, i.e. 4.
So the users should notice the change on the first release since deprecating.
Or, After a month or more, may or may not, all the users should migration/following this change.
§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
Utilitiesand thenTerminal. - In the terminal type the following command to disable SIP:
csrutil disable(csrutil enableto re-enable SIP). - Reboot your machine.
To run the example, build it as follows:
cargo b --example dump_process_registersThen 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
- Option 1: GNU General Public License Version 3.0, or
- Option 2: Apache License, Version 2.0
at your option.
§Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in mach-sys by you,
as defined in the dual licensing under GPL-3.0 OR Apache-2.0, shall be
both licensed as above, without any additional terms or conditions.
To locally test the library, run:
$ ./tomake.sh nostd --target=x86_64-apple-darwin --any-args-accept-by-rustc
$ ./tomake.sh test --target=<your_platform> --any-args-accept-by-cargo
$ echo "for other args please see the bash script named tomake.sh"where you can replace the --target with the target you
want to test (e.g. aarch64-apple-darwin) and use Rustup if you need to use different Rust version, (e.g. stable, 1.33.0, etc.).
Modules§
- boolean
- This module corresponds to
mach/i386/boolean.h. - bootstrap
- This module corresponds to
bootstrap.h - clock
- This module roughly corresponds to
mach/clock.h. - clock_
priv - This module roughly corresponds to
mach/clock_priv.h. - clock_
reply - This module roughly corresponds to
mach/clock_reply.h. - clock_
types - This module roughly corresponds to
mach/clock_types.h. - dlfcn
- This module roughly corresponds to
dlfcn.h. - dyld
- This module roughly corresponds to
mach-o/dyld.h. - dyld_
images - This module roughly corresponds to
mach-o/dyld_images.h. - dyld_
kernel - This module roughly corresponds to
mach/dyld_kernel.h. - error
- This module roughly corresponds to
mach/mach_error.h. - exc
- This module roughly corresponds to
mach/exc.h. - exception_
types - This module roughly corresponds to
mach/exception_types.h. - ffi
- imports C types from core::ffi
- kern_
return - This module corresponds to
mach/kern_return.h. - libproc
- This module roughly corresponds to
libproc.h. - loader
- This module roughly corresponds to
mach-o/loader.h. - mach_
init - This module corresponds to
mach/mach_init.h. - mach_
port - This module corresponds to
mach/mach_port.h - mach_
time - This module corresponds to
mach/mach_time.h - mach_
types - This module corresponds to
mach/mach_types.h - memory_
object_ types - This module roughly corresponds to
mach/memory_object_types.h. - message
- This module corresponds to
mach/message.h. - ndr
- This module roughly corresponds to
mach/ndr.h. - nlist
- This module roughly corresponds to
mach-o/nlist.h. - port
- This module corresponds to
mach/port.h - semaphore
- This module corresponds to
mach/semaphore.h - structs
- This module corresponds to
mach/i386/_structs.handmach/arm/_structs.h. - sync_
policy - This module corresponds to
mach/sync_policy.h - task
- This module corresponds to
mach/task.h. - task_
info - This module roughly corresponds to
mach/task_info.h. - thread_
act - This module corresponds to
mach/thread_act.defs. - thread_
policy - This module corresponds to
mach/thread_policy.h. - thread_
status - This module corresponds to
mach/thread_status.h. - time_
value - traps
- This module corresponds to
mach/mach_traps.h. - vm
- This module roughly corresponds to
mach/mach_vm.defs. - vm_
attributes - This module corresponds to
mach/vm_attributes.h. - vm_
behavior - This module corresponds to
mach/vm_behavior.h. - vm_
inherit - This module corresponds to
mach/vm_inherit.h. - vm_
page_ size - This module roughly corresponds to
mach/vm_page_size.h - vm_prot
- This module corresponds to
mach/vm_prot.h. - vm_
purgable - This module corresponds to
mach/vm_purgable.h. - vm_
region - This module roughly corresponds to
mach/vm_region.h. - vm_
statistics - This module roughly corresponds to
mach/vm_statistics.h - vm_sync
- This module corresponds to
mach/vm_sync.h. - vm_
types - This module roughly corresponds to
mach/i386/vm_types.h(on amd64) andmach/arm/vm_types.h(on aarch64).