Skip to content
Newer
Older
100644 148 lines (119 sloc) 3.41 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
66888f4 @nelhage Make the man page and -h both mention all available options.
authored Apr 25, 2011
59 .B \-s
60 .IP
61
62 By default, reptyr will move any file descriptors in the target that were
63 connected to the target's controlling terminal to point to the new terminal. The
64 .B -s
65 option will cause reptyr to unconditionally attach file descriptors 0, 1, and 2
66 in the target, even if the target has no controlling terminal or they are not
67 connected to a terminal.
68 .LP
69
f03de19 @nelhage Add a manpage, and remove the now-redundant BUGS file.
authored Feb 4, 2011
70 .B \-v
71 .IP
72 Print the version of
73 .B reptyr
74 and exit.
75 .LP
76
77 .B \-h
78 .IP
79 Print a usage message and exit.
80 .LP
81
3fa5657 @nelhage Document the -V option in usage and man pages.
authored Dec 21, 2011
82 .B \-V
83 .IP
84 Print verbose debug output while running.
85 .LP
86
f03de19 @nelhage Add a manpage, and remove the now-redundant BUGS file.
authored Feb 4, 2011
87 .SH NOTES
88
89 .B reptyr
90 depends on the
91 .BR ptrace (2)
92 system call to attach to the remote program. On Ubuntu Maverick and higher, this
93 ability is disabled by default for security reasons. You can enable it
94 temporarily by doing
95 .IP
96 # echo 0 > /proc/sys/kernel/yama/ptrace_scope
97 .LP
98 as root, or permanently by editing the file
99 .IR /etc/sysctl.d/10-ptrace.conf ,
100 which also contains more information about this setting.
101
102 .SH BUGS
103
104 When attaching to some curses programs, they will not redraw the screen right
105 away, and a
106 .B ^L
107 or similar will be needed to force a redraw.
108
109 Similarly, after attaching to certain programs, the old terminal will be left in
110 an odd state, and a
111 .B clear
112 or even
113 .B reset
114 may be required before the old terminal is usable again.
115
116 Attaching to rtorrent (and probably some other apps) doesn't work right
117 (rtorrent stops accepting input) (The problem is that rtorrent is using epoll to
118 poll stdin, and we don't update the internal reference that the epoll fd has to
119 the old tty).
120
121 Attaching to a process with children doesn't work right. This should be possible
122 to fix -- I just need to ptrace each child individually and do the same games to
123 it.
124
125 Attaching a
126 .BR less (1)
127 process doesn't work if you have a
128 .I .lessfilter
129 file, as
130 .BR less
131 leaves around a zombie child in this case. This could be worked around.
132
133 Bugs should be reported to the author (see below) or via the issue tracker on
134 GitHub.
135
136 .SH AUTHORS
137
138 reptyr was written by Nelson Elhage <nelhage@nelhage.com>.
139
140 .SH HOMEPAGE
141
142 .URL https://github.com/nelhage/reptyr
143
144 .SH SEE ALSO
145
146 .BR neercs (1),
147 .BR screen (1)
Something went wrong with that request. Please try again.