abduco.1 (4763B)
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