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 .El
 146 .Pp
 147 See the
 148 .Sx FILES
 149 section for environment variables used in determining the location
 150 of unix domain sockets representing sessions.
 151 .Sh FILES
 152 .
 153 All session related information is stored in the following directories (first
 154 to succeed is used):
 155 .Bl -bullet
 156 .It
 157 .Ev $ABDUCO_SOCKET_DIR/abduco
 158 .It
 159 .Ev $HOME/.abduco
 160 .It
 161 .Ev $TMPDIR/abduco/$USER
 162 .It
 163 .Ev /tmp/abduco/$USER
 164 .El
 165 .
 166 .Pp
 167 However, if a given session
 168 .Ic name
 169 represents either a relative or absolute path it is used unmodified.
 170 .
 171 .
 172 .Sh EXAMPLES
 173 .
 174 Start a new session (assuming
 175 .Xr dvtm 1
 176 is in
 177 .Ev $PATH )
 178 with
 179 .Pp
 180 .Dl $ abduco -c my-session
 181 .Pp
 182 do some work, then detach by pressing
 183 .Aq Ctrl+\e ,
 184 list existing session by running
 185 .Nm
 186 without any arguments and later reattach with
 187 .Pp
 188 .Dl $ abduco -a my-session
 189 .Pp
 190 Alternatively, we can also explicitly specify the command to run.
 191 .Pp
 192 .Dl $ abduco -c my-session /bin/sh
 193 .Pp
 194 Attach with a
 195 .Aq Ctrl+z
 196 as detach key.
 197 .Pp
 198 .Dl $ abduco -e ^z -a my-session
 199 .Pp
 200 Send a command to an existing session.
 201 .Pp
 202 .Dl $ echo make | abduco -a my-session
 203 .Pp
 204 Or in a slightly more interactive fashion.
 205 .Pp
 206 .Dl $ abduco -p my-session
 207 .Dl make
 208 .Dl ^D
 209 .
 210 .Sh SEE ALSO
 211 .Xr dvtm 1 ,
 212 .Xr dtach 1 ,
 213 .Xr tmux 1 ,
 214 .Xr screen 1
 215 .
 216 .Sh AUTHOR
 217 .Nm
 218 is written by
 219 .An Marc André Tanner Aq mat at brain-dump.org