abduco.1

   1 .Dd March 18, 2018
   2 .Dt ABDUCO 1
   3 .Os abduco VERSION
   4 .
   5 .Sh NAME
   6 .Nm abduco
   7 .Nd terminal session manager
   8 .
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Fl a
  12 .Op options ...
  13 .Cm name
  14 .
  15 .Nm
  16 .Fl A
  17 .Op options ...
  18 .Cm name
  19 .Cm command Op args ...
  20 .
  21 .Nm
  22 .Fl c
  23 .Op options ...
  24 .Cm name
  25 .Cm command Op args ...
  26 .
  27 .Nm
  28 .Fl n
  29 .Op options ...
  30 .Cm name
  31 .Cm command Op args ...
  32 .
  33 .Sh DESCRIPTION
  34 .
  35 .Nm
  36 disassociates a given application from its controlling
  37 terminal, thereby providing roughly the same session attach/detach support as
  38 .Xr screen 1 ,
  39 .Xr tmux 1 ,
  40 or
  41 .Xr dtach 1 .
  42 .Pp
  43 A session comprises of an
  44 .Nm
  45 server process which spawns a user
  46 command in its own pseudo terminal
  47 .Pq see Xr pty 7 .
  48 Each session is given a name represented by a unix domain socket
  49 .Pq see Xr unix 7
  50 stored in the local file system.
  51 .Nm
  52 clients can connect to it and their standard input output streams
  53 are relayed to the command supervised by the server.
  54 .Pp
  55 .Nm
  56 operates on the raw I/O byte stream without interpreting any terminal
  57 escape sequences. As a consequence the terminal state is not preserved
  58 across sessions. If this functionality is desired, it should be provided
  59 by another utility such as
  60 .Xr dvtm 1 .
  61 .
  62 .Ss ACTIONS
  63 .
  64 If no command line arguments are given, all currently active sessions are
  65 listed sorted by their respective creation date. Lines starting with an
  66 asterisk
  67 .Pq *
  68 indicate that at least one client is currently connected.
  69 A plus sign
  70 .Pq +
  71 signals that the command terminated while no client was connected.
  72 Attaching to the session will print its exit status.
  73 The next column shows the PID of the server process, followed by the session
  74 .Ic name .
  75 .Pp
  76 .Nm
  77 provides different actions of which one must be provided.
  78 .
  79 .Bl -tag -width indent
  80 .It Fl a
  81 Attach to an existing session.
  82 .It Fl A
  83 Try to connect to an existing session, upon failure create said session and attach immediately to it.
  84 .It Fl c
  85 Create a new session and attach immediately to it.
  86 .It Fl n
  87 Create a new session but do not attach to it.
  88 .El
  89 .
  90 .Ss OPTIONS
  91 .
  92 Additionally the following options can be provided to further tweak
  93 the behavior.
  94 .Bl -tag -width indent
  95 .It Fl e Ar detachkey
  96 Set the key to detach. Defaults to
  97 .Aq Ctrl+\e
  98 which is specified as ^\\ i.e. Ctrl is represented as a caret
  99 .Pq ^ .
 100 .It Fl f
 101 Force creation of session when there is an already terminated session of the same name,
 102 after showing its exit status.
 103 .It Fl l
 104 Attach with the lowest priority, meaning this client will be the last to control the size.
 105 .It Fl p
 106 Pass through content of standard input to the session. Implies the
 107 .Fl q
 108 and
 109 .Fl l
 110 options.
 111 .It Fl q
 112 Be quiet, do not print informative messages.
 113 .It Fl r
 114 Read-only session, user input is ignored.
 115 .It Fl v
 116 Print version information and exit.
 117 .El
 118 .
 119 .Sh SIGNALS
 120 .
 121 .Bl -tag -width indent
 122 .It Dv SIGWINCH
 123 Whenever the primary client resizes its terminal the server process will deliver a
 124 .Ev SIGWINCH
 125 signal to the supervised process.
 126 .It Dv SIGUSR1
 127 If for some reason the unix domain socket representing a session is deleted, sending
 128 .Ev SIGUSR1
 129 to the server process will recreate it.
 130 .It Dv SIGTERM
 131 Detaches a client.
 132 .El
 133 .
 134 .Sh ENVIRONMENT
 135 .
 136 .Bl -tag -width indent
 137 .It Ev ABDUCO_CMD
 138 If
 139 .Ic command
 140 is not specified, the environment variable
 141 .Ev $ABDUCO_CMD
 142 is examined, if it is not set
 143 .Xr dvtm 1
 144 is executed.
 145 .It Ev ABDUCO_SESSION
 146 The current session name available to the supervised command.
 147 .It Ev ABDUCO_SOCKET
 148 The absolute path of the session socket available to the supervised command.
 149 .El
 150 .Pp
 151 See the
 152 .Sx FILES
 153 section for environment variables used in determining the location
 154 of unix domain sockets representing sessions.
 155 .Sh FILES
 156 .
 157 All session related information is stored in the following directories (first
 158 to succeed is used):
 159 .Bl -bullet
 160 .It
 161 .Ev $ABDUCO_SOCKET_DIR/abduco
 162 .It
 163 .Ev $HOME/.abduco
 164 .It
 165 .Ev $TMPDIR/abduco/$USER
 166 .It
 167 .Ev /tmp/abduco/$USER
 168 .El
 169 .
 170 .Pp
 171 However, if a given session
 172 .Ic name
 173 represents either a relative or absolute path it is used unmodified.
 174 .
 175 .
 176 .Sh EXAMPLES
 177 .
 178 Start a new session (assuming
 179 .Xr dvtm 1
 180 is in
 181 .Ev $PATH )
 182 with
 183 .Pp
 184 .Dl $ abduco -c my-session
 185 .Pp
 186 do some work, then detach by pressing
 187 .Aq Ctrl+\e ,
 188 list existing session by running
 189 .Nm
 190 without any arguments and later reattach with
 191 .Pp
 192 .Dl $ abduco -a my-session
 193 .Pp
 194 Alternatively, we can also explicitly specify the command to run.
 195 .Pp
 196 .Dl $ abduco -c my-session /bin/sh
 197 .Pp
 198 Attach with a
 199 .Aq Ctrl+z
 200 as detach key.
 201 .Pp
 202 .Dl $ abduco -e ^z -a my-session
 203 .Pp
 204 Send a command to an existing session.
 205 .Pp
 206 .Dl $ echo make | abduco -a my-session
 207 .Pp
 208 Or in a slightly more interactive fashion.
 209 .Pp
 210 .Dl $ abduco -p my-session
 211 .Dl make
 212 .Dl ^D
 213 .
 214 .Sh SEE ALSO
 215 .Xr dvtm 1 ,
 216 .Xr dtach 1 ,
 217 .Xr tmux 1 ,
 218 .Xr screen 1
 219 .
 220 .Sh AUTHOR
 221 .Nm
 222 is written by
 223 .An Marc André Tanner Aq mat at brain-dump.org