aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d4fa33c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+# taketty
+
+Create a new PTY that other programs can attach to as their controlling terminal.
+
+## Building
+
+```bash
+make
+```
+
+## Usage
+
+### Creating a PTY
+
+Run `taketty` to create a new PTY and forward I/O:
+
+```bash
+./taketty
+```
+
+This will:
+- Create a new PTY via `/dev/ptmx`
+- Configure and unlock the slave
+- Put the master terminal in raw mode
+- Forward stdin/stdout to the PTY master
+- Print the slave path to stderr as `TAKETTY_PTY=/dev/pts/N`
+
+### Attaching to the PTY
+
+#### Method 1: Using the attach helper (with job control)
+
+In another terminal, capture the PTY path and use the attach helper to exec a shell:
+
+```bash
+export TAKETTY_PTY=/dev/pts/N
+./attach $TAKETTY_PTY bash
+```
+
+Or pass the command directly:
+
+```bash
+./attach /dev/pts/N bash
+```
+
+The attach helper will:
+- Call `setsid()` to create a new session
+- Open the slave PTY
+- Use `ioctl(TIOCSCTTY)` to make it the controlling terminal
+- Redirect stdin/stdout/stderr to the PTY
+- Execute the specified program (or return if none specified)
+
+#### Method 2: Source the bash script (I/O only, no job control)
+
+If you only need I/O redirection without full job control:
+
+```bash
+export TAKETTY_PTY=/dev/pts/N
+source ./attach.sh
+```
+
+Note: This method redirects file descriptors but doesn't set the controlling terminal, so signals like Ctrl+C won't work as expected.
+
+## Architecture
+
+- **taketty.c**: Creates PTY master, forwards I/O between stdin/stdout and master FD
+- **attach.c**: Helper to attach a process to the PTY slave as controlling terminal
+- **attach.sh**: Bash script for simple I/O redirection (sourcing only)