Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fhunleth/dtach

Patches to http://dtach.sourceforge.net/ (These have been merged!)
https://github.com/fhunleth/dtach

Last synced: about 1 month ago
JSON representation

Patches to http://dtach.sourceforge.net/ (These have been merged!)

Awesome Lists containing this project

README 

        
1. INTRODUCTION



dtach is a program written in C that emulates the detach feature of

screen, which allows a program to be executed in an environment that is

protected from the controlling terminal. For instance, the program under

the control of dtach would not be affected by the terminal being

disconnected for some reason.



dtach was written because screen did not adequately meet my needs; I did

not need screen's extra features, such as support for multiple

terminals or terminal emulation support. screen was also too big,

bulky, and had source code that was difficult to understand.



screen also interfered with my use of full-screen applications such as

emacs and ircII, due to its excessive interpretation of the stream between

the program and the attached terminals. dtach does not have a terminal

emulation layer, and passes the raw output stream of the program to the

attached terminals. The only input processing that dtach does perform is

scanning for the detach character (which signals dtach to detach from

the program) and processing the suspend key (which tells dtach to

temporarily suspend itself without affecting the running program), and both

of these can both be disabled if desired.



Contrary to screen, dtach has minimal features, and is extremely tiny.

This allows dtach to be more easily audited for bugs and security

holes, and makes it accessible in environments where space is limited,

such as on rescue disks.



dtach has only been tested on the Linux/x86 platform, however it should

be easily portable to other variants of Unix. It currently assumes that

the host system uses POSIX termios, and has a working forkpty function

available.



2. QUICK START



Compiling dtach should be simple, as it uses autoconf:



	$ ./configure

	$ make



If all goes well, a dtach binary should be built for your system. You can

then copy it to the appropriate place on your system.



dtach uses Unix-domain sockets to represent sessions; these are network

sockets that are stored in the filesystem. You specify the name of the

socket that dtach should use when creating or attaching to dtach sessions.



For example, let's create a new session that is running ircII. We will use

/tmp/foozle as the session's socket:



	$ dtach -A /tmp/foozle irc RuneB irc.freenode.net



Here, -A tells dtach to either create a new session or attach to the

existing session. If the session at /tmp/foozle does not exist yet, the

program will be executed. If it does exist, then dtach will attach to

the existing session.



dtach has another attach mode, which is specified by using -a. The -a

mode attaches to an already existing session, but will not create a new

session. Each attaching process can have a separate detach character,

suspend behavior, and redraw method, which are explained in the

following sections.



dtach is able to attach to the same session multiple times, though you

will likely encounter problems if your terminals have different window

sizes. Pressing ^L (Ctrl-L) will reset the window size of the program to

match the current terminal.



3. DETACHING FROM THE SESSION



By default, dtach scans the keyboard input looking for the detach character.

When the detach character is pressed, dtach will detach from the current

session and exit, leaving the program running in the background. You can then

re-attach to the program by running dtach again with -A or -a.



The default detach character is ^\ (Ctrl-\). This can be changed by supplying

the -e option to dtach when attaching. For example:



	$ dtach -a /tmp/foozle -e '^A'



That command would attach to the existing session at /tmp/foozle and use

^A (Ctrl-A) as the detach character, instead of the default ^\.



You can disable processing of the detach character by supplying the -E

option to dtach when attaching.



4. SUSPENDING DTACH



By default, dtach also processes the suspend key (^Z or Ctrl-Z) itself,

instead of passing it to the program. Thus, pressing suspend only suspends

the attaching process, instead of the running program. This can be very

useful for applications such as ircII, where you may not necessarily want

the program to be suspended.



Processing of the suspend key can be disabled by supplying the -z option

to dtach when attaching.



5. REDRAW METHOD



When attaching, dtach can use one of three methods to redraw the screen

(none, ctrl_l, or winch). By default, dtach uses the ctrl_l method,

which simply sends a ^L (Ctrl-L) character to the program if the

terminal is in character-at-a-time and no-echo mode. The winch method

forces a WINCH signal to be sent to the program, and the none method

disables redrawing completely.



For example, this command tells dtach to attach to a session at

/tmp/foozle and use the winch redraw method:



	$ dtach -a /tmp/foozle -r winch



When creating a new session (with the -c or -A modes), the specified

method is used as the default redraw method for the session.



6. CHANGES



The changes in version 0.8 are:

- When using dtach -A or dtach -c, the master will now wait until the client

  attaches before trying to read from the program being executed. This avoids

  a race condition when the program prints something and exits before the

  client can attach itself.

- Instead of exiting quietly, dtach will now report any errors that occur

  while trying to execute the program.

- dtach -n can now be used without a terminal.

- dtach -A will now try to detect and remove stale sockets.

- Removed a Linux-specific escape sequence from the code that restores the

  original terminal settings.

- Changed dtach.1 to use \- for the dashes in command line options, and

  fix an ambiguous backslash.

- Use non-blocking mode in the master process, and avoid data loss by ensuring

  that at least one attaching client succesfully completes a write.

- Fix -e ^ to work with lowercase characters.



The changes in version 0.7 are:

- The redraw method can now be explicitly specified on the command line

  (either no redraw at all, the old ^L character method, and the new WINCH

  signal method), since many programs only handle one or the other properly.

- Changed the default redraw method back to the old ^L character method.

- Changed the attach code to check the return value of select more carefully.

- Changed the SIGWINCH handler to reinstall itself, to handle systems that

  always reset the handler.

- Added more proper process group handling.



The changes in version 0.6 are:

- Redraws are now handled by sending the child process a WINCH signal instead

  of by sending a ^L character. This should help prevent line-oriented

  programs (such as bash) from clearing the screen excessively.

- Flow control is now disabled when setting raw mode on the terminal.

- Switched to using select instead of poll.

- Changed some exits to exit succesfully instead of non-sucessfully.

- Updated my email address.

- Updated to Autoconf 2.59, renaming some files in the process.



The changes in version 0.5 are:

- Fix fd leakage.

- Prevent atexit from being called twice on dtach -A.



The changes in version 0.4 are:

- Slightly improved README and dtach.1

- Portability updates thanks to sourceforge's compile farm. dtach should now

  work on: FreeBSD, Debian/alpha, Debian/sparc, Debian/PPC, and Solaris.



The changes in version 0.3 are:

- Fixed a typo in dtach.1

- Changed the attach code so that it tells the master when a suspend

  occurs.

- Decreased the client <-> master packet size.

- Changed the master to send a stream of text to attaching clients

  instead of sending a huge packet all the time.

- Use getrlimit and dynamically allocate the data structures, if

  possible.

- Added some more autoconf checks.

- Initial sourceforge release.

 

7. AUTHOR



dtach is (C)Copyright 2004-2008 Ned T. Crigler, and is under the GNU General

Public License.



Comments and suggestions about dtach are welcome, and can be sent to

the author at: .