11. INTRODUCTION 2 3dtach is a program written in C that emulates the detach feature of 4screen, which allows a program to be executed in an environment that is 5protected from the controlling terminal. For instance, the program under 6the control of dtach would not be affected by the terminal being 7disconnected for some reason. 8 9dtach was written because screen did not adequately meet my needs; I did 10not need screen's extra features, such as support for multiple 11terminals or terminal emulation support. screen was also too big, 12bulky, and had source code that was difficult to understand. 13 14screen also interfered with my use of full-screen applications such as 15emacs and ircII, due to its excessive interpretation of the stream between 16the program and the attached terminals. dtach does not have a terminal 17emulation layer, and passes the raw output stream of the program to the 18attached terminals. The only input processing that dtach does perform is 19scanning for the detach character (which signals dtach to detach from 20the program) and processing the suspend key (which tells dtach to 21temporarily suspend itself without affecting the running program), and both 22of these can both be disabled if desired. 23 24Contrary to screen, dtach has minimal features, and is extremely tiny. 25This allows dtach to be more easily audited for bugs and security 26holes, and makes it accessible in environments where space is limited, 27such as on rescue disks. 28 29dtach has only been tested on the Linux/x86 platform, however it should 30be easily portable to other variants of Unix. It currently assumes that 31the host system uses POSIX termios, and has a working forkpty function 32available. 33 34dtach may need access to various devices in the filesystem depending on what 35forkpty does. For example, dtach on Linux usually needs access to /dev/ptmx 36and /dev/pts. 37 382. QUICK START 39 40Compiling dtach should be simple, as it uses autoconf: 41 42 $ ./configure 43 $ make 44 45If all goes well, a dtach binary should be built for your system. You can 46then copy it to the appropriate place on your system. 47 48dtach uses Unix-domain sockets to represent sessions; these are network 49sockets that are stored in the filesystem. You specify the name of the 50socket that dtach should use when creating or attaching to dtach sessions. 51 52For example, let's create a new session that is running ircII. We will use 53/tmp/foozle as the session's socket: 54 55 $ dtach -A /tmp/foozle irc RuneB irc.freenode.net 56 57Here, -A tells dtach to either create a new session or attach to the 58existing session. If the session at /tmp/foozle does not exist yet, the 59program will be executed. If it does exist, then dtach will attach to 60the existing session. 61 62dtach has another attach mode, which is specified by using -a. The -a 63mode attaches to an already existing session, but will not create a new 64session. Each attaching process can have a separate detach character, 65suspend behavior, and redraw method, which are explained in the 66following sections. 67 68dtach is able to attach to the same session multiple times, though you 69will likely encounter problems if your terminals have different window 70sizes. Pressing ^L (Ctrl-L) will reset the window size of the program to 71match the current terminal. 72 73dtach also has a mode that copies the contents of standard input to a session. 74For example: 75 76 $ echo -ne 'cd /var/log\nls -l\n' | dtach -p /tmp/foozle 77 78The contents are sent verbatim including any embedded control characters (e.g. 79the newline characters in the above example), and dtach will not scan the 80input for a detach character. 81 823. DETACHING FROM THE SESSION 83 84By default, dtach scans the keyboard input looking for the detach character. 85When the detach character is pressed, dtach will detach from the current 86session and exit, leaving the program running in the background. You can then 87re-attach to the program by running dtach again with -A or -a. 88 89The default detach character is ^\ (Ctrl-\). This can be changed by supplying 90the -e option to dtach when attaching. For example: 91 92 $ dtach -a /tmp/foozle -e '^A' 93 94That command would attach to the existing session at /tmp/foozle and use 95^A (Ctrl-A) as the detach character, instead of the default ^\. 96 97You can disable processing of the detach character by supplying the -E 98option to dtach when attaching. 99 1004. SUSPENDING DTACH 101 102By default, dtach also processes the suspend key (^Z or Ctrl-Z) itself, 103instead of passing it to the program. Thus, pressing suspend only suspends 104the attaching process, instead of the running program. This can be very 105useful for applications such as ircII, where you may not necessarily want 106the program to be suspended. 107 108Processing of the suspend key can be disabled by supplying the -z option 109to dtach when attaching. 110 1115. REDRAW METHOD 112 113When attaching, dtach can use one of three methods to redraw the screen 114(none, ctrl_l, or winch). By default, dtach uses the ctrl_l method, 115which simply sends a ^L (Ctrl-L) character to the program if the 116terminal is in character-at-a-time and no-echo mode. The winch method 117forces a WINCH signal to be sent to the program, and the none method 118disables redrawing completely. 119 120For example, this command tells dtach to attach to a session at 121/tmp/foozle and use the winch redraw method: 122 123 $ dtach -a /tmp/foozle -r winch 124 125When creating a new session (with the -c or -A modes), the specified 126method is used as the default redraw method for the session. 127 1286. CHANGES 129 130The changes in version 0.9 are: 131- Added AIX support. 132- Added dtach -N, a mode similar to dtach -n, except dtach will stay in the 133 foreground instead of daemonizing. 134- Added dtach -p, which copies the contents of standard input to a session. 135- dtach will no longer send 255 bytes of garbage to the program when read() 136 returns an error. 137- The executable bit is now set on the socket if clients are attached, and 138 cleared when all clients have detached. 139- The initial state of signals such as SIGPIPE are now preserved when 140 executing the program, instead of having the program start with some signals 141 ignored. 142- A buffer overflow no longer occurs when a long socket path name is used, and 143 dtach will now try to use chdir to get around the length limitation if 144 necessary. 145 146The changes in version 0.8 are: 147- When using dtach -A or dtach -c, the master will now wait until the client 148 attaches before trying to read from the program being executed. This avoids 149 a race condition when the program prints something and exits before the 150 client can attach itself. 151- Instead of exiting quietly, dtach will now report any errors that occur 152 while trying to execute the program. 153- dtach -n can now be used without a terminal. 154- dtach -A will now try to detect and remove stale sockets. 155- Removed a Linux-specific escape sequence from the code that restores the 156 original terminal settings. 157- Changed dtach.1 to use \- for the dashes in command line options, and 158 fix an ambiguous backslash. 159- Use non-blocking mode in the master process, and avoid data loss by ensuring 160 that at least one attaching client succesfully completes a write. 161- Fix -e ^<char> to work with lowercase characters. 162 163The changes in version 0.7 are: 164- The redraw method can now be explicitly specified on the command line 165 (either no redraw at all, the old ^L character method, and the new WINCH 166 signal method), since many programs only handle one or the other properly. 167- Changed the default redraw method back to the old ^L character method. 168- Changed the attach code to check the return value of select more carefully. 169- Changed the SIGWINCH handler to reinstall itself, to handle systems that 170 always reset the handler. 171- Added more proper process group handling. 172 173The changes in version 0.6 are: 174- Redraws are now handled by sending the child process a WINCH signal instead 175 of by sending a ^L character. This should help prevent line-oriented 176 programs (such as bash) from clearing the screen excessively. 177- Flow control is now disabled when setting raw mode on the terminal. 178- Switched to using select instead of poll. 179- Changed some exits to exit succesfully instead of non-sucessfully. 180- Updated my email address. 181- Updated to Autoconf 2.59, renaming some files in the process. 182 183The changes in version 0.5 are: 184- Fix fd leakage. 185- Prevent atexit from being called twice on dtach -A. 186 187The changes in version 0.4 are: 188- Slightly improved README and dtach.1 189- Portability updates thanks to sourceforge's compile farm. dtach should now 190 work on: FreeBSD, Debian/alpha, Debian/sparc, Debian/PPC, and Solaris. 191 192The changes in version 0.3 are: 193- Fixed a typo in dtach.1 194- Changed the attach code so that it tells the master when a suspend 195 occurs. 196- Decreased the client <-> master packet size. 197- Changed the master to send a stream of text to attaching clients 198 instead of sending a huge packet all the time. 199- Use getrlimit and dynamically allocate the data structures, if 200 possible. 201- Added some more autoconf checks. 202- Initial sourceforge release. 203 2047. AUTHOR 205 206dtach is (C)Copyright 2004-2016 Ned T. Crigler, and is under the GNU General 207Public License. 208 209Comments and suggestions about dtach are welcome, and can be sent to 210the author at: <crigler@users.sourceforge.net>. 211