Introducing a new way to review your PRs.

Read the announcement

rikkaapps / shizuku

Using system APIs directly with adb/root privileges from normal apps through a Java process started with app_process.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / manager-native-starter-helpers

Manager native starter helpers

Overview

The manager app's native starter is built from manager/…/CMakeLists.txt as an executable target named libshizuku.so. That target compiles manager/…/starter.cpp with the shared helpers in misc.cpp, selinux.cpp, and cgroup.cpp, links against Android log and cxx::cxx, and is stripped further in non-Debug builds. The same CMake file also builds an unrelated shared adb library from adb_pairing.cpp and misc.cpp; helper.cpp and android.cpp are not part of either target in this CMake file.

manager/…/starter.cpp is the native entrypoint used to launch the Java server process. Its main accepts an optional --apk=<path> override, rejects callers that are neither root nor shell/adb (uid 0 or 2000), initializes SELinux function pointers via se::init(), and performs root-only environment cleanup before spawning the server. For root launches it tries to move itself out of app-specific cgroups with switch_cgroup(), switches to init's mount namespace on Android API 29+ via switch_mnt_ns(1), and checks whether u:r:untrusted_app:s0 can make and transfer binder calls to the current su context. A binder denial exits with EXIT_FATAL_BINDER_BLOCKED_BY_SELINUX before the Java service is started.

Before launch, starter.cpp scans /proc with foreach_proc() from manager/…/misc.cpp, reads each process command line with get_proc_name(), and kills any existing process whose name is exactly shizuku_server. It then resolves the manager APK path either from --apk= or by running pm path moe.shizuku.privileged.api, trimming the package: result with trim(). start_server() forks: the parent prints the child PID and exits successfully, while the child creates a new session, redirects stdio to /dev/null, sets CLASSPATH to the APK, derives -Dshizuku.library.path from the APK directory and build ABI, and execvps /system/bin/app_process with main class rikka.shizuku.server.ShizukuService and nice name shizuku_server. Debug builds add JDWP/compiler flags chosen by API level.

manager/…/cgroup.cpp contains the low-level cgroup writer used by starter.cpp: it appends the current PID to <cgroup>/cgroup.procs if that file exists. starter.cpp tries /acct, /dev/cg2_bpf, /sys/fs/cgroup, and, when ro.config.per_app_memcg is not false, /dev/memcg/apps. Failure to switch cgroups only logs a warning and does not stop server launch.

manager/…/selinux.cpp provides a small SELinux abstraction that defaults to procfs/xattr-based implementations and upgrades them at runtime when libselinux.so is present under /system/lib or /system/lib64. The exported function pointers in selinux.h cover getcon, setcon, setfilecon, selinux_check_access, and freecon. The fallback selinux_check_access always returns success, so the starter's binder preflight only has real enforcement when se::init() successfully resolves libselinux.so symbols.

manager/…/misc.cpp is the starter's process and filesystem helper collection. It wraps interrupted reads in fdgets(), reads /proc/<pid>/cmdline, tests numeric /proc directory names, iterates process IDs, copies files with sendfile(), searches memory byte-by-byte, switches mount namespaces with setns() on /proc/<pid>/ns/mnt, and trims strings in place. manager/…/logging.h supplies Android log macros and PLOGE, with LOG_TAG defaulting to Shizuku unless a source file defines it first.

manager/…/helper.cpp is a JNI helper entrypoint rather than part of the starter executable. Its JNI_OnLoad initializes SELinux symbols and registers setSELinuxContext(String): int on moe/shizuku/server/utils/NativeHelper; the native method calls se::setcon() with the supplied context string and logs failures with PLOGE. Because this file is not referenced by manager/…/CMakeLists.txt, changes here also require checking whatever external build path or historical packaging path is expected to load it.

manager/…/android.cpp and android.h define cached property readers for ro.build.version.sdk and ro.build.version.preview_sdk under the android:: namespace. The current starter code instead calls android_get_device_api_level() directly in starter.cpp, and android.cpp is not listed in libshizuku.so's sources.

Coupling

  • If the server package, process name, or main class changes, update the constants in manager/…/starter.cpp together with the Java/server packaging that supplies rikka.shizuku.server.ShizukuService; otherwise the native starter may resolve the wrong APK, fail pm path, or launch app_process with a class that does not exist.
  • If the APK layout or native library ABI directories change, verify run_server() in manager/…/starter.cpp; it derives -Dshizuku.library.path as <dirname(apk_path)>/lib/<ABI> and does not probe alternate split or extracted-library locations.
  • If SELinux checks are tightened, verify both manager/…/selinux.cpp and starter.cpp: starter.cpp treats se::selinux_check_access() as authoritative, but selinux.cpp silently falls back to an implementation that always permits when libselinux.so is unavailable or unresolved.
  • If the cgroup locations for rooted launches change on newer Android releases, update both the path order in starter.cpp::switch_cgroup() and the write behavior in manager/…/cgroup.cpp; the helper appends raw PIDs to cgroup.procs and reports only a warning on failure.
  • If helper.cpp is made part of the JNI build, add it deliberately to manager/…/CMakeLists.txt and check its registration string moe/shizuku/server/utils/NativeHelper; a package or method-signature drift will make JNI_OnLoad fail registration.
  • If code starts using android::GetApiLevel() or android::GetPreviewApiLevel() from manager/…/android.cpp, add android.cpp to the relevant CMake target; the current starter target does not compile that translation unit.

Risks

  • manager/…/misc.cpp can leak src_fd in copyfileat() when fstat(src_fd) fails, because that error path returns without closing the opened source descriptor. This matters if the helper is reused in a loop or long-lived JNI library.
  • manager/…/selinux.cpp makes failed or missing libselinux.so look permissive through the fallback __selinux_check_access(). On devices where symbol loading fails, starter.cpp may skip the intended binder-denial fatal path and only fail later when the Java server tries to communicate over binder.
  • manager/…/starter.cpp kills processes solely by /proc/<pid>/cmdline matching shizuku_server. If another process uses the same nice name, the starter can send it SIGKILL; if an existing Shizuku process is protected from the current uid, launch exits with EXIT_FATAL_KILL before resolving the APK path.