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