reptyr(1)

💖 reptyr — reparent a running program to a new terminal 💖

okay bestie, welcome to the reptyr(1) manual page, General Commands Manual edition, and honestly? this little tool is a whole game changer. sit down, hydrate, let's go 🫶

✨ SYNOPSIS ✨

reptyr PID

reptyr -l|-L [COMMAND [ARGS]]

that's it. that's the whole summoning ritual 🌸

🦋 DESCRIPTION 🦋

reptyr is a utility for taking an existing running program and attaching it to a new terminal. started a long-running process over ssh but you have to leave and you don't want to interrupt it? no because same 😭. just start a screen, use reptyr to grab it, and then kill the ssh session and head on home. main character exit, periodt 💅

here's the tea on how it works: reptyr attaches to the target program using ptrace(2), redirects the relevant file descriptors, and changes the program's controlling terminal (see tty(4)). and it's that last detail that makes reptyr work so much better than alternatives like retty(1). like, not even a competition bestie ✨

after attaching a program, the program will look either backgrounded or suspended to the shell it was launched from (depends on the shell, they all have their own vibe). for maximal safety you can run:

bg; disown

in the old shell to remove the association with the program. but ngl, reptyr will attempt to make sure the target program keeps running even if you close the shell without doing that. so it's giving safety net, not giving guarantee 👑 (do the bg; disown thing though, be a responsible icon).

🌈 OPTIONS 🌈

• -T — uses an alternate mode of attaching, called "TTY-stealing". in this mode, reptyr will not ptrace(2) the target process — instead it attempts to discover the terminal emulator for that process' pty, and steal the master end of the pty. this mode is more reliable and flexible in many circumstances (for instance, it can attach all processes on a tty, rather than just a single process 🔥). however, as a downside, children of sshd(8) cannot be attached via -T unless reptyr is run as root. more info about tty-stealing lives at ⟨https://blog.nelhage.com/2014/08/new-reptyr-feature-tty-stealing/⟩ 📖
• -l, -L [COMMAND [ARGS]] — instead of attaching to a new process, create a new pty pair, proxy the master end to the current terminal, and then print the name of the slave pty. you can pass that to e.g. gdb's set inferior-tty option 🎀

if an optional COMMAND and ARGS are passed in conjunction with -l, that command will be executed as a child of reptyr with the REPTYR_PTY environment variable set to the name of the slave pty. and if -L is used instead of -l, then fds 0-2 of the child will also be redirected to point to the slave, and the child will be run in a fresh session with the slave as its controlling terminal. fancy fr fr 💅

• -s — by default, reptyr will move any file descriptors in the target that were connected to the target's controlling terminal so they point to the new terminal. the -s option makes reptyr unconditionally attach file descriptors 0, 1, and 2 in the target — even if the target has no controlling terminal, or those fds aren't connected to a terminal. no vibe check required, just full send 🌈
• -v — print the version of reptyr and exit. short and sweet 🍓
• -h — print a usage message and exit 🧚
• -V — print verbose debug output while running. for when you need the play-by-play commentary 🎙️

👑 NOTES 👑

reptyr depends on the ptrace(2) system call to attach to the remote program. on Ubuntu Maverick and higher, this ability is disabled by default for security reasons 😤. you can enable it temporarily by doing:

# echo 0 > /proc/sys/kernel/yama/ptrace_scope

as root, or permanently by editing the file /etc/sysctl.d/10-ptrace.conf, which also contains more information about this setting. so like, permission slip required, bestie 💜

💀 BUGS 💀

listen. it's not perfect, no one is, and the manpage is being very honest with us:

• when attaching to some curses programs, they will not redraw the screen right away, and a ^L or similar will be needed to force a redraw. rude of them honestly 🙈
• similarly, after attaching to certain programs, the old terminal will be left in an odd state, and a clear or even reset may be required before the old terminal is usable again. it's giving haunted house energy 👻
• attaching to rtorrent (and probably some other apps) doesn't work right (rtorrent stops accepting input). the problem is that rtorrent is using epoll to poll stdin, and we don't update the internal reference that the epoll fd has to the old tty. mystery unsolved 🔍
• attaching to a process with children doesn't work right. this should be possible to fix — the author just needs to ptrace each child individually and do the same games to it. so like, technically doable, pending 💀
• attaching a less(1) process doesn't work if you have a .lessfilter file, as less leaves around a zombie child in this case. this could be worked around. zombie child!! spooky 🧟

bugs should be reported to the author (see below) or via the issue tracker on GitHub. don't suffer in silence, bestie, tell someone 📣

💖 AUTHORS 💖

reptyr was written by Nelson Elhage <nelhage@nelhage.com>. icon behavior, no cap 👑

🌸 HOMEPAGE 🌸

⟨https://github.com/nelhage/reptyr⟩ 🦋

🎀 SEE ALSO 🎀

neercs(1), screen(1) ✨

and that's the whole page, bestie!! this manual page is from reptyr(1), dated 03 Feb 2011 — vintage but still absolutely slaying 💅💖🌸