forked from github/abduco
Convert manual page to mdoc(7) format, restructure content
This commit is contained in:
Marc André Tanner
parent
884e3bb2ca
commit
5eb7317971
348
abduco.1
348
abduco.1
|
|
@ -1,151 +1,219 @@
|
||||||
.TH ABDUCO 1 abduco\-VERSION
|
.Dd March 18, 2018
|
||||||
.nh
|
.Dt ABDUCO 1
|
||||||
.SH NAME
|
.Os abduco VERSION
|
||||||
abduco - terminal session manager
|
.
|
||||||
.SH SYNOPSIS
|
.Sh NAME
|
||||||
.B abduco
|
.Nm abduco
|
||||||
.RB [ \-e
|
.Nd terminal session manager
|
||||||
.IR detachkey ]
|
.
|
||||||
.RB [ \-r ]
|
.Sh SYNOPSIS
|
||||||
.RB [ \-f ]
|
.Nm
|
||||||
.RB \-c
|
.Fl a
|
||||||
.RB name
|
.Op options ...
|
||||||
.RB command
|
.Cm name
|
||||||
.RI [ args \ ... "" ]
|
.
|
||||||
.br
|
.Nm
|
||||||
.B abduco
|
.Fl A
|
||||||
.RB [ \-e
|
.Op options ...
|
||||||
.IR detachkey ]
|
.Cm name
|
||||||
.RB [ \-r ]
|
.Cm command Op args ...
|
||||||
.RB [ \-f ]
|
.
|
||||||
.RB \-n
|
.Nm
|
||||||
.RB name
|
.Fl c
|
||||||
.RB command
|
.Op options ...
|
||||||
.RI [ args \ ... "" ]
|
.Cm name
|
||||||
.br
|
.Cm command Op args ...
|
||||||
.B abduco
|
.
|
||||||
.RB [ \-e
|
.Nm
|
||||||
.IR detachkey ]
|
.Fl n
|
||||||
.RB [ \-r ]
|
.Op options ...
|
||||||
.RB [ \-f ]
|
.Cm name
|
||||||
.RB [ \-l ]
|
.Cm command Op args ...
|
||||||
.RB \-A
|
.
|
||||||
.RB name
|
.Sh DESCRIPTION
|
||||||
.RB command
|
.
|
||||||
.RI [ args \ ... "" ]
|
.Nm
|
||||||
.br
|
disassociates a given application from its controlling
|
||||||
.B abduco
|
terminal, thereby providing roughly the same session attach/detach support as
|
||||||
.RB [ \-e
|
.Xr screen 1 ,
|
||||||
.IR detachkey ]
|
.Xr tmux 1 ,
|
||||||
.RB [ \-r ]
|
or
|
||||||
.RB [ \-l ]
|
.Xr dtach 1 .
|
||||||
.RB \-a
|
.Pp
|
||||||
.RB name
|
A session comprises of an
|
||||||
.br
|
.Nm
|
||||||
.SH DESCRIPTION
|
server process which spawns a user
|
||||||
.B abduco
|
command in its own pseudo terminal
|
||||||
provides a way to disconnect a given application from its controlling
|
.Pq see Xr pty 7 .
|
||||||
terminal, thus it provides roughly the same session attach/detach support as
|
Each session is given a name represented by a unix domain socket
|
||||||
.BR screen(1) , " tmux(1)" " or" " dtach(1)".
|
.Pq see Xr unix 7
|
||||||
|
stored in the local file system.
|
||||||
If the
|
.Nm
|
||||||
.BR command
|
clients can connect to it and their standard input output streams
|
||||||
to execute is not specified, the environment variable
|
are relayed to the command supervised by the server.
|
||||||
.BR $ABDUCO_CMD
|
.Pp
|
||||||
is examined, if it is not set
|
.Nm
|
||||||
.BR dvtm(1)
|
operates on the raw I/O byte stream without interpreting any terminal
|
||||||
is executed.
|
escape sequences. As a consequence the terminal state is not preserved
|
||||||
|
across sessions. If this functionality is desired, it should be provided
|
||||||
All session related information is stored in the following directories (first
|
by another utility such as
|
||||||
to succeed is used):
|
.Xr dvtm 1 .
|
||||||
.RS
|
.
|
||||||
.nf
|
.Ss ACTIONS
|
||||||
.PP
|
.
|
||||||
.B $ABDUCO_SOCKET_DIR/abduco
|
If no command line arguments are given, all currently active sessions are
|
||||||
.B $HOME/.abduco
|
listed sorted by their respective creation date. Lines starting with an
|
||||||
.B $TMPDIR/abduco/$USER
|
asterisk
|
||||||
.B /tmp/abduco/$USER
|
.Pq *
|
||||||
.fi
|
indicate that at least one client is currently connected.
|
||||||
.RE
|
|
||||||
|
|
||||||
However if a given session name represents either a relative or absolute path
|
|
||||||
it is used unmodified.
|
|
||||||
|
|
||||||
If for some reason the
|
|
||||||
.BR unix(7)
|
|
||||||
domain socket representing a session is deleted, sending
|
|
||||||
.BR SIGUSR1
|
|
||||||
to the server process will recreate it.
|
|
||||||
|
|
||||||
If standard input does not refer to a terminal (or the
|
|
||||||
.B -p
|
|
||||||
option was given), its content is passed through to the underlying session.
|
|
||||||
.SH OPTIONS
|
|
||||||
If no command line arguments are given all currently active sessions are
|
|
||||||
printed sorted by their respective creation date. Lines starting with an
|
|
||||||
asterik
|
|
||||||
.BR *
|
|
||||||
indicate that at least one client is connected.
|
|
||||||
A plus sign
|
A plus sign
|
||||||
.BR +
|
.Pq +
|
||||||
indicates that the command terminated while no client was connected, attach
|
signals that the command terminated while no client was connected.
|
||||||
to get its exit status.
|
Attaching to the session will print its exit status.
|
||||||
.TP
|
The next column shows the PID of the server process, followed by the session
|
||||||
.B \-v
|
.Ic name .
|
||||||
Print version information to standard output and exit.
|
.Pp
|
||||||
.TP
|
.Nm
|
||||||
.B \-r
|
provides different actions of which one must be provided.
|
||||||
Readonly session, i.e. user input is ignored.
|
.
|
||||||
.TP
|
.Bl -tag -width indent
|
||||||
.B \-e \fIdetachkey\fR
|
.It Fl a
|
||||||
Set the key to detach which by default is set to CTRL+\\ i.e. ^\\ to detachkey.
|
Attach to an existing session.
|
||||||
.TP
|
.It Fl A
|
||||||
.BI \-f
|
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,
|
Force creation of session when there is an already terminated session of the same name,
|
||||||
after showing its exit status.
|
after showing its exit status.
|
||||||
.TP
|
.It Fl l
|
||||||
.BI \-c
|
|
||||||
Create a new session and attach immediately to it.
|
|
||||||
.TP
|
|
||||||
.BI \-n
|
|
||||||
Create a new session but do not attach to it.
|
|
||||||
.TP
|
|
||||||
.BI \-A
|
|
||||||
Try to connect to an existing session, upon failure create said session and attach immediately to it.
|
|
||||||
.TP
|
|
||||||
.BI \-a
|
|
||||||
Attach to an existing session.
|
|
||||||
.TP
|
|
||||||
.BI \-l
|
|
||||||
Attach with the lowest priority, meaning this client will be the last to control the size.
|
Attach with the lowest priority, meaning this client will be the last to control the size.
|
||||||
.TP
|
.It Fl p
|
||||||
.BI \-q
|
|
||||||
Be quiet, do not print informative messages.
|
|
||||||
.TP
|
|
||||||
.BI \-p
|
|
||||||
Pass through content of standard input to the session. Implies the
|
Pass through content of standard input to the session. Implies the
|
||||||
.B \-q
|
.Fl q
|
||||||
and
|
and
|
||||||
.B \-l
|
.Fl l
|
||||||
options.
|
options.
|
||||||
.SH EXAMPLE
|
.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.
|
||||||
|
.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
|
Start a new session (assuming
|
||||||
.BR dvtm(1)
|
.Xr dvtm 1
|
||||||
is in
|
is in
|
||||||
.BR $PATH )
|
.Ev $PATH )
|
||||||
with
|
with
|
||||||
.nf
|
.Pp
|
||||||
|
.Dl $ abduco -c my-session
|
||||||
.B abduco -c my-session
|
.Pp
|
||||||
|
|
||||||
.fi
|
|
||||||
do some work, then detach by pressing
|
do some work, then detach by pressing
|
||||||
.B CTRL+\e
|
.Aq Ctrl+\e ,
|
||||||
and later reattach with
|
list existing session by running
|
||||||
.nf
|
.Nm
|
||||||
|
without any arguments and later reattach with
|
||||||
.B abduco -a my-session
|
.Pp
|
||||||
|
.Dl $ abduco -a my-session
|
||||||
.fi
|
.Pp
|
||||||
.SH AUTHOR
|
Alternatively, we can also explicitly specify the command to run.
|
||||||
abduco is written by Marc André Tanner <mat at brain-dump.org>
|
.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 AUTHOR
|
||||||
|
.Nm
|
||||||
|
is written by
|
||||||
|
.An Marc André Tanner Aq mat at brain-dump.org
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue