mirror of https://github.com/martanne/abduco
227 lines
4.7 KiB
Groff
227 lines
4.7 KiB
Groff
.Dd March 18, 2018
|
|
.Dt ABDUCO 1
|
|
.Os abduco VERSION
|
|
.
|
|
.Sh NAME
|
|
.Nm abduco
|
|
.Nd terminal session manager
|
|
.
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl a
|
|
.Op options ...
|
|
.Cm name
|
|
.
|
|
.Nm
|
|
.Fl A
|
|
.Op options ...
|
|
.Cm name
|
|
.Cm command Op args ...
|
|
.
|
|
.Nm
|
|
.Fl c
|
|
.Op options ...
|
|
.Cm name
|
|
.Cm command Op args ...
|
|
.
|
|
.Nm
|
|
.Fl n
|
|
.Op options ...
|
|
.Cm name
|
|
.Cm command Op args ...
|
|
.
|
|
.Sh DESCRIPTION
|
|
.
|
|
.Nm
|
|
disassociates a given application from its controlling
|
|
terminal, thereby providing roughly the same session attach/detach support as
|
|
.Xr screen 1 ,
|
|
.Xr tmux 1 ,
|
|
or
|
|
.Xr dtach 1 .
|
|
.Pp
|
|
A session comprises of an
|
|
.Nm
|
|
server process which spawns a user
|
|
command in its own pseudo terminal
|
|
.Pq see Xr pty 7 .
|
|
Each session is given a name represented by a unix domain socket
|
|
.Pq see Xr unix 7
|
|
stored in the local file system.
|
|
.Nm
|
|
clients can connect to it and their standard input output streams
|
|
are relayed to the command supervised by the server.
|
|
.Pp
|
|
.Nm
|
|
operates on the raw I/O byte stream without interpreting any terminal
|
|
escape sequences.
|
|
As a consequence the terminal state is not preserved across sessions.
|
|
If this functionality is desired, it should be provided by another
|
|
utility such as
|
|
.Xr dvtm 1 .
|
|
.
|
|
.Ss ACTIONS
|
|
.
|
|
If no command line arguments are given, all currently active sessions are
|
|
listed sorted by their respective creation date.
|
|
Lines starting with an asterisk
|
|
.Pq *
|
|
indicate that at least one client is currently connected.
|
|
A plus sign
|
|
.Pq +
|
|
signals that the command terminated while no client was connected.
|
|
Attaching to the session will print its exit status.
|
|
The next column shows the PID of the server process, followed by the session
|
|
.Ic name .
|
|
.Pp
|
|
.Nm
|
|
provides different actions of which one must be provided.
|
|
.
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
Attach to an existing session.
|
|
.It Fl A
|
|
Try to connect to an existing session, upon failure create said session and attach immediately to it.
|
|
.It Fl c
|
|
Create a new session and attach immediately to it.
|
|
.It Fl n
|
|
Create a new session but do not attach to it.
|
|
.El
|
|
.
|
|
.Ss OPTIONS
|
|
.
|
|
Additionally the following options can be provided to further tweak
|
|
the behavior.
|
|
.Bl -tag -width indent
|
|
.It Fl e Ar detachkey
|
|
Set the key to detach.
|
|
Defaults to
|
|
.Aq Ctrl+\e
|
|
which is specified as ^\\ i.e. Ctrl is represented as a caret
|
|
.Pq ^ .
|
|
.It Fl f
|
|
Force creation of session when there is an already terminated session of the same name,
|
|
after showing its exit status.
|
|
.It Fl l
|
|
Attach with the lowest priority, meaning this client will be the last to control the size.
|
|
.It Fl p
|
|
Pass through content of standard input to the session.
|
|
Implies the
|
|
.Fl q
|
|
and
|
|
.Fl l
|
|
options.
|
|
.It Fl q
|
|
Be quiet, do not print informative messages.
|
|
.It Fl r
|
|
Read-only session, user input is ignored.
|
|
.It Fl v
|
|
Print version information and exit.
|
|
.El
|
|
.
|
|
.Sh SIGNALS
|
|
.
|
|
.Bl -tag -width indent
|
|
.It Dv SIGWINCH
|
|
Whenever the primary client resizes its terminal the server process will deliver a
|
|
.Ev SIGWINCH
|
|
signal to the supervised process.
|
|
.It Dv SIGUSR1
|
|
If for some reason the unix domain socket representing a session is deleted, sending
|
|
.Ev SIGUSR1
|
|
to the server process will recreate it.
|
|
.It Dv SIGTERM
|
|
Detaches a client.
|
|
.El
|
|
.
|
|
.Sh ENVIRONMENT
|
|
.
|
|
.Bl -tag -width indent
|
|
.It Ev ABDUCO_CMD
|
|
If
|
|
.Ic command
|
|
is not specified, the environment variable
|
|
.Ev $ABDUCO_CMD
|
|
is examined, if it is not set
|
|
.Xr dvtm 1
|
|
is executed.
|
|
.It Ev ABDUCO_SESSION
|
|
The current session name available to the supervised command.
|
|
.It Ev ABDUCO_SOCKET
|
|
The absolute path of the session socket available to the supervised command.
|
|
.El
|
|
.Pp
|
|
See the
|
|
.Sx FILES
|
|
section for environment variables used in determining the location
|
|
of unix domain sockets representing sessions.
|
|
.Sh FILES
|
|
.
|
|
All session related information is stored in the following directories (first
|
|
to succeed is used):
|
|
.Bl -bullet
|
|
.It
|
|
.Ev $ABDUCO_SOCKET_DIR/abduco
|
|
.It
|
|
.Ev $HOME/.abduco
|
|
.It
|
|
.Ev $TMPDIR/abduco/$USER
|
|
.It
|
|
.Ev /tmp/abduco/$USER
|
|
.El
|
|
.
|
|
.Pp
|
|
However, if a given session
|
|
.Ic name
|
|
represents either a relative or absolute path it is used unmodified.
|
|
.
|
|
.
|
|
.Sh EXAMPLES
|
|
.
|
|
Start a new session (assuming
|
|
.Xr dvtm 1
|
|
is in
|
|
.Ev $PATH )
|
|
with
|
|
.Pp
|
|
.Dl $ abduco -c my-session
|
|
.Pp
|
|
do some work, then detach by pressing
|
|
.Aq Ctrl+\e ,
|
|
list existing session by running
|
|
.Nm
|
|
without any arguments and later reattach with
|
|
.Pp
|
|
.Dl $ abduco -a my-session
|
|
.Pp
|
|
Alternatively, we can also explicitly specify the command to run.
|
|
.Pp
|
|
.Dl $ abduco -c my-session /bin/sh
|
|
.Pp
|
|
Attach with a
|
|
.Aq Ctrl+z
|
|
as detach key.
|
|
.Pp
|
|
.Dl $ abduco -e ^z -a my-session
|
|
.Pp
|
|
Send a command to an existing session.
|
|
.Pp
|
|
.Dl $ echo make | abduco -a my-session
|
|
.Pp
|
|
Or in a slightly more interactive fashion.
|
|
.Pp
|
|
.Dl $ abduco -p my-session
|
|
.Dl make
|
|
.Dl ^D
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr dvtm 1 ,
|
|
.Xr dtach 1 ,
|
|
.Xr tmux 1 ,
|
|
.Xr screen 1
|
|
.
|
|
.Sh AUTHORS
|
|
.Nm
|
|
is written by
|
|
.An Marc André Tanner Aq mat at brain-dump.org
|