retty.1

   1 .TH RETTY 1 2006-08-14
   2
   3 .SH NAME
   4 retty - Attach process running on another terminal
   5
   6 .SH SYNOPSIS
   7 .B retty [-v] [-h] [-0 fd] [-1 fd] [-2 fd] PID
   8
   9 .SH DESCRIPTION
  10
  11 .B retty
  12 is a simple tool which will let you attach process currently running on
  13 another terminal. Unlike screen, you need to make no special provisions
  14 in advance - just get the process' pid and attach it anytime.
  15
  16 Before using
  17 .B retty
  18 on a given application on a given system the first time, please make sure
  19 it works on the system and for the application (start another instance and
  20 try to attach it). It is unfortunately quite fragile and if your setup does
  21 not match its taste, it can even crash the attached application. Some
  22 applications won't work because they do I/O on other fds than 0, 1, 2 (that's
  23 fixable), some applications won't work because they do I/O on
  24 .B /dev/tty
  25 (that's unfixable without kernel changes).
  26 .B Trying to run retty on a kernel with security patches applied (non-exec stack in particular) will result in the attached process segfaulting immediatelly!
  27
  28 Non-violently killing
  29 .B retty
  30 should provide for a proper detach - after that,
  31 the process can be used on the original terminal again. Multiple subsequent
  32 .B retty
  33 attachments of a single process are possible, but the process does I/O
  34 only on the last one - don't forget to detach them in the right sequence,
  35 or your application will break (in this case, it is maybe better to attach
  36 already running retty than attaching single application twice).
  37
  38 You can also use escape sequences to detach a process and possibly do other
  39 things. The escape character is "`" (lowercase of "~") and "`h" will give you
  40 list of possible escape sequences. The escape character must be immediately
  41 preceded by an enter.
  42
  43 By default,
  44 .B retty
  45 attaches file descriptors 0, 1 and 2 of the process. That should be enough
  46 in most cases, but will not do in some special ones. In such case, you have
  47 to check /proc/<PID>/fd and force
  48 .B retty
  49 to attach correct file descriptors instead. OpenSSH is one such program - it
  50 duplicates file descriptors and then uses duplicated ones.
  51
  52 .RE
  53 .SH OPTIONS
  54 .TP
  55 .B "\-v"
  56 Display version information.
  57 .TP
  58 .B "\-h"
  59 Display usage information.
  60 .TP
  61 .B "\-0 fd"
  62 Specify file descriptor that process we want to attach uses as input.
  63 Default value is 0 (stdin).
  64 .TP
  65 .B "\-1 fd"
  66 Specify file descriptor that process we want to attach uses as output.
  67 Default value is 1 (stdout).
  68 .TP
  69 .B "\-2 fd"
  70 Specify file descriptor that process we want to attach uses for error
  71 outputs. Default value is 2 (stderr).
  72 .TP
  73 .B PID
  74 PID of process that we want to attach. If retty is run as ordinary user,
  75 it can attach only processes owned by that user. If run as root, retty
  76 can attach probably anything (not always good idea).
  77
  78 .RE
  79 .SH BUGS
  80 .PD
  81 .IP \(bu
  82 .I retty
  83 is x86-specific and works only on Linux with executable stack.
  84 .IP \(bu
  85 The attached process' controlling terminal is not switched appropriately,
  86 which causes many funny effects (e.g.
  87 .I mutt
  88 not properly adjusting for your
  89 window size, but this can be fixed by going into editor and back) and annoying
  90 bugs (ctrl+c not delivered properly).
  91 .IP \(bu
  92 If you attach
  93 .I bash
  94 it imagines EOF on stdin. Attaching and detaching multiple times without
  95 any activity in the meantime will cause it to die.
  96 .IP \(bu
  97 Attempts to attach
  98 .I less
  99 just don't work even with input fd override. This might or might not be
 100 fixed in the future, depending on cause (which is unknown now).
 101 .IP \(bu
 102 You must make sure both
 103 .I retty
 104 and the attached process run with the same uid. Running
 105 .I retty
 106 as root and attached process as regular user will
 107 .B NOT
 108 work.
 109 .I su
 110 to the same user first.
 111 (This is because
 112 .I retty
 113 makes the attached process open a tty created by
 114 .I retty
 115 which fails since the attached process has insufficient permissions.
 116 .I retty
 117 should check uid of the target process and
 118 .I chown
 119 the tty accordingly.)
 120
 121 .RE
 122 .SH "SEE ALSO"
 123 screen(1)