forked from martanne/abduco
-
Notifications
You must be signed in to change notification settings - Fork 0
/
abduco.1
229 lines (229 loc) · 4.85 KB
/
abduco.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
.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 F1 s
Silently Attach/Detach without switching to/from alternate buffer. Useful for automatically reconnecting
persistent SSH connections that don't want to alter terminal state when reconnecting.
.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