Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
reptyr(1)		    General Commands Manual		     reptyr(1)

       reptyr -	Reparent a running program to a	new terminal

       reptyr PID

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

       reptyr  is a utility for	taking an existing running program and attach-
       ing it to a new terminal. Started a long-running	process	over ssh,  but
       have  to	leave and don't	want to	interrupt it? Just start a screen, use
       reptyr to grab it, and then kill	the ssh	session	and head on home.

       reptyr works by attaching to the	target program using ptrace(2),	 redi-
       recting	relevant file descriptors, and changing	the program's control-
       ling terminal (See tty(4)) It is	this last  detail  that	 makes	reptyr
       work much better	than alternatives such as retty(1).

       After  attaching	 a program, the	program	will appear to be either back-
       grounded	or suspended to	the shell it was launched from	(depending  on
       the shell). For maximal safety you can run

	      bg; disown

       in the old shell	to remove the association with the program, but	reptyr
       will attempt to ensure that the target program remains running even  if
       you close the shell without doing so.


	      Use  an  alternate  mode	of  attaching, "TTY-stealing". In this
	      mode, reptyr will	not ptrace(2) the target process, but will at-
	      tempt  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). How-
	      ever,  as	a downside, children of	sshd(8)	cannot be attached via
	      -T unless	reptyr is run as root. See <
	      2014/08/new-reptyr-feature-tty-stealing/>	 for  more information
	      about 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. This can be passed	to e.g.	 gdb's set in-
	      ferior-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. 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	termi-


	      By  default, reptyr will move any	file descriptors in the	target
	      that were	connected to  the  target's  controlling  terminal  to
	      point  to	 the  new terminal. The	-s option will cause reptyr to
	      unconditionally attach file descriptors 0, 1, and	2 in the  tar-
	      get,  even if the	target has no controlling terminal or they are
	      not connected to a terminal.


	      Print the	version	of reptyr and exit.


	      Print a usage message and	exit.


	      Print verbose debug output while running.

       reptyr depends on the ptrace(2) system call to  attach  to  the	remote
       program.	On Ubuntu Maverick and higher, this ability is disabled	by de-
       fault 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.

       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.

       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  be-
       fore the	old terminal is	usable again.

       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).

       Attaching to a process with children doesn't work right.	This should be
       possible	to fix -- I just need to ptrace	each child individually	and do
       the same	games to it.

       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.

       Bugs should be reported to the author (see  below)  or  via  the	 issue
       tracker on GitHub.

       reptyr was written by Nelson Elhage <>.


       neercs(1), screen(1)

				  03 Feb 2011			     reptyr(1)


Want to link to this manual page? Use this URL:

home | help