Skip to content
Newer
Older
100644 132 lines (106 sloc) 3 KB
f03de19 @nelhage Add a manpage, and remove the now-redundant BUGS file.
authored Feb 3, 2011
1 .mso www.tmac
2 .TH reptyr 1 "03 Feb 2011"
3 .SH NAME
4 reptyr \- Reparent a running program to a new terminal
5 .SH SYNOPSIS
6 .B reptyr
7 .I PID
8
9 .B reptyr \-l
10
11 .SH DESCRIPTION
12
13 .B reptyr
14 is a utility for taking an existing running program and
15 attaching it to a new terminal. Started a long-running process over
16 ssh, but have to leave and don't want to interrupt it? Just start a
17 screen, use
18 .B reptyr
19 to grab it, and then kill the ssh session and head
20 on home.
21 .LP
22 .B reptyr
23 works by attaching to the target program using
24 .BR ptrace (2),
25
26 redirecting relevant file descriptors, and changing the program's controlling
27 terminal (See
28 .BR tty (4))
29 It is this last detail that makes
30 .B reptyr
31 work much better than alternatives such as
32 .BR retty (1).
33
34 .LP
35 After attaching a program, the program will appear to be either backgrounded or
36 suspended to the shell it was launched from (depending on the shell). For
37 maximal safety you can run
38 .IP
39 bg; disown
40 .LP
41
42 in the old shell to remove the association with the program, but
43 .B reptyr
44 will attempt to ensure that the target program remains running even if you close
45 the shell without doing so.
46
47 .SH OPTIONS
48
49 .B \-l
50 .IP
51 Instead of attaching to a new process, create a new pty pair, proxy the master
52 end to the current terminal, and then print the name of the slave pty. This can
53 be passed to e.g.
54 .B gdb\'s
55 .I set inferior-tty
56 option.
57 .LP
58
59 .B \-v
60 .IP
61 Print the version of
62 .B reptyr
63 and exit.
64 .LP
65
66 .B \-h
67 .IP
68 Print a usage message and exit.
69 .LP
70
71 .SH NOTES
72
73 .B reptyr
74 depends on the
75 .BR ptrace (2)
76 system call to attach to the remote program. On Ubuntu Maverick and higher, this
77 ability is disabled by default for security reasons. You can enable it
78 temporarily by doing
79 .IP
80 # echo 0 > /proc/sys/kernel/yama/ptrace_scope
81 .LP
82 as root, or permanently by editing the file
83 .IR /etc/sysctl.d/10-ptrace.conf ,
84 which also contains more information about this setting.
85
86 .SH BUGS
87
88 When attaching to some curses programs, they will not redraw the screen right
89 away, and a
90 .B ^L
91 or similar will be needed to force a redraw.
92
93 Similarly, after attaching to certain programs, the old terminal will be left in
94 an odd state, and a
95 .B clear
96 or even
97 .B reset
98 may be required before the old terminal is usable again.
99
100 Attaching to rtorrent (and probably some other apps) doesn't work right
101 (rtorrent stops accepting input) (The problem is that rtorrent is using epoll to
102 poll stdin, and we don't update the internal reference that the epoll fd has to
103 the old tty).
104
105 Attaching to a process with children doesn't work right. This should be possible
106 to fix -- I just need to ptrace each child individually and do the same games to
107 it.
108
109 Attaching a
110 .BR less (1)
111 process doesn't work if you have a
112 .I .lessfilter
113 file, as
114 .BR less
115 leaves around a zombie child in this case. This could be worked around.
116
117 Bugs should be reported to the author (see below) or via the issue tracker on
118 GitHub.
119
120 .SH AUTHORS
121
122 reptyr was written by Nelson Elhage <nelhage@nelhage.com>.
123
124 .SH HOMEPAGE
125
126 .URL https://github.com/nelhage/reptyr
127
128 .SH SEE ALSO
129
130 .BR neercs (1),
131 .BR screen (1)
Something went wrong with that request. Please try again.