From b566fe0f839b5f0cf08f3691a0518be7d9a5ca39 Mon Sep 17 00:00:00 2001 From: "GitHub Action (docs)" Date: Sun, 17 Sep 2023 02:25:41 +0000 Subject: [PATCH] Add docs --- docs/index.html | 69 +++++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 28 deletions(-) diff --git a/docs/index.html b/docs/index.html index c5601d9..0c7dc52 100644 --- a/docs/index.html +++ b/docs/index.html @@ -108,7 +108,7 @@

cmd/injector a command line program linked with the static library

-Windows

+Windows (MSVC)

Open a Visual Studio command prompt and run the following commands:

$ git clone https://github.com/kubo/injector.git # Or use any other tool
$ cd injector
@@ -133,6 +133,17 @@

cmd/injector.exe a command line program linked the static library (release build)

+Windows (mingw-w64)

+

On MSYS2:

+
$ git clone https://github.com/kubo/injector.git
+
$ cd injector
+
$ CC=gcc make
+

Cross-compilation on Linux:

+
$ git clone https://github.com/kubo/injector.git
+
$ cd injector
+
$ CC=x86_64-w64-mingw32-gcc OS=Windows_NT make
+

The environment variable OS=Windows_NT must be set on Linux.

+

MacOS

$ git clone https://github.com/TheOiseth/injector.git
$ cd injector
@@ -154,9 +165,9 @@

$ chmod +x sign.sh
$ ./sign.sh

If injector still does not work after signing, reboot the system.

-

+

Usage

-

+

C API

#include <injector.h>
@@ -194,35 +205,32 @@

injector_attach
int injector_attach(injector_t **injector, injector_pid_t pid)
Attach to the specified process.
injector_uninject
int injector_uninject(injector_t *injector, void *handle)
Uninject the shared library specified by handle.
injector_detach
int injector_detach(injector_t *injector)
Detach from the attached process and destroy the specified handle.
-

+

Command line program

See Usage section and Sample section in linux-inject and substitute inject with injector in the page.

-

+

Tested Architectures

-

+

Linux

- +

x86_64:

- + - +
injector process \ target process x86_64 i386 x32(*1)
x86_64 😃 success(*2) 😃 success(*3) 😃 success(*3)
x86_64 😃 success(*2) 😃 success(*3) 😃 success(*6)
i386 💀 failure(*4) 😃 success(*3) 💀 failure(*5)
x32(*1) 💀 failure(*4) 😃 success(*3) 💀 failure(*5)
x32(*1) 💀 failure(*4) 😃 success(*6) 💀 failure(*5)

*1: x32 ABI
*2: tested on github actions with both glibc and musl.
*3: tested on github actions with glibc.
*4: failure with 64-bit target process isn't supported by 32-bit process.
*5: failure with x32-ABI target process is supported only by x86_64.
+ *6: tested on a local machine. CONFIG_X86_X32 isn't enabled in github actions.

- +

ARM:

@@ -235,9 +243,7 @@

injector process \ target process arm64 armhf armel

*1: failure with 64-bit target process isn't supported by 32-bit process.

- +

MIPS:

@@ -251,20 +257,18 @@

*1: tested on debian 11 mips64el on QEMU.
*2: failure with 64-bit target process isn't supported by 32-bit process.

+

PowerPC:

injector process \ target process mips64el mipsel (n32) mipsel (o32)
@@ -276,7 +280,7 @@

*1: failure with x64 target process isn't supported by x86 process.
*2: tested on github actions

-

On arm machine:

+

Windows 11 on Arm:

injector process \ target process x64 x86
@@ -291,7 +295,16 @@

injector process \ target process arm64 arm64ec x64 x86 arm32
arm32 💀 failure 💀 failure 💀 failure 💀 failure 😃 success
-

+

Wine (on Linux x86_64):

+ + + + + + + +
injector process \ target process x64 x86
x64 😃 success 💀 failure
x86 💀 failure 😃 success
+

MacOS

@@ -304,7 +317,7 @@

*1: failure with x86_64 target process isn't supported by x86_64 process on ARM64 machine. Tested on github actions.
*2: failure with arm64 target process isn't supported by x86_64 process.
*3: failure with x86_64 target process isn't supported by arm64 process.

-

+

Caveats

The following restrictions are only on Linux.

Injector doesn't work where ptrace() is disallowed.

@@ -315,7 +328,7 @@

Injector calls functions inside of a target process interrupted by ptrace(). If the target process is interrupted while holding a non-reentrant lock and injector calls a function requiring the same lock, the process stops forever. If the lock type is reentrant, the status guarded by the lock may become inconsistent. As far as I checked, dlopen() internally calls malloc() requiring non-reentrant locks. dlopen() also uses a reentrant lock to guard information about loaded files.

On Linux x86_64 injector_inject_in_cloned_thread in place of injector_inject may be a solution of the locking issue. It calls dlopen() in a thread created by clone(). Note that no wonder there are unexpected pitfalls because some resources allocated in pthread_create() lack in the clone()-ed thread. Use it at your own risk.

-

+

License

Files under [include][] and [src][] are licensed under LGPL 2.1 or later.
Files under [cmd][] are licensed under GPL 2 or later.