screen-ls - pretty-prints the output from 'screen -ls' screen-ls -h
screen-ls -V
screen-ls [OPTION...] [--] [SCREEN_OPTIONS]The screen-ls program invokes the GNU screen(1) program with the -ls option to obtain a list of screen session names, and pretty prints the output. See "EXAMPLES" below.
By default, prints the screen(1) session names (without the leading pid and . char) from the output of the screen -ls command.
With the -l (--long) option, will print the full output in a readable table.
With the -p (--show-pid) option, will include the pid and <.> char which are suppressed by default.
Any options not recognized by screen-ls will be passed through to screen(1). You can explicitly stop screen-ls options processing by using the -- pseudo-option; all options after that will be passed through to screen(1).
When working with GNU screen(1), it is not uncommon to accumulate a large number of screen(1) sessions. This naturally leads to the need to locate "interesting" sessions at a later time when you wish to reconnect to them. And that, of course, becomes more difficult as the number of screen(1) sessions increases.
Pretty-printing the output makes it easier to read by inspection, and suppressing everything except the screen(1) session names from the output often simplifies downstream processing in a Unix pipeline.
Below are the command line options recognized by screen-ls. Any options not recognized by screen-ls will be passed through to the screen(1) subprocess.
You can explicitly stop screen-ls options processing by using the -- pseudo-option; all options after that will be passed through to screen(1).
Print help usage message
Use a long listing format.
Causes screen-ls to display the '<pid>.' prefix in screen session names. By default, screen-ls suppresses the output of this prefix.
Do not sort output; list screen(1) sessions in order output by the screen -ls subprocess invocation.
By default, screen-ls sorts the output by screen(1) session name; this is an optimization for the common case. Prior to this behavior, the most common invocation of screen-ls was:
$ screen-ls | sortThe -U (--unsorted) option exists to allow you to disable this behavior, though.
Print the version of the program to stdout and then exit.
Turn on verbose mode. Two or more -v options turns on tracing (invokes set -x; this is primarily intended for developers).
For reference, the default output of screen -ls might look like this:
$ screen -ls
There are screens on:
779.screen-wrappers-dev (07/08/2013 01:09:19 PM) (Attached)
26043.datomic-local (07/07/2013 02:20:50 PM) (Attached)
14926.emacs-dev (06/30/2013 07:57:14 PM) (Attached)
24078.activemq-mysql-prod (06/23/2013 01:22:41 AM) (Detached)
803.build-build (05/22/2013 06:02:49 AM) (Detached)
12522.release-5.5 (05/18/2013 06:09:31 AM) (Attached)
5200.mutt (05/17/2013 10:21:59 AM) (Attached)
...
49 Sockets in /var/run/screen/S-ads.That output is truncated, but you get the idea. When there are only two or three screen(1) session active, then the default output works fine. However, when there are a large number of screen(1) sessions active (such as in above example, where there are 49), it can become difficult to find the interesting ones. Enter screen-ls.
By default, screen-ls strips away all data except the screen(1) session name, and it removes the pid and following . character from those, as well. Here is how the above output appears when generated by screen-ls:
$ screen-ls
activemq-mysql-prod
build-build
datomic-local
emacs-dev
mutt
release-5.5
screen-wrappers-dev
...That is both easier to read, and easier to process by downstream tools in a pipeline.
Note that screen-ls sorted the output by the screen(1) session name automatically. You can disable the sorting behavior by providing the -U (--unsorted) option:
$ screen-ls -U
screen-wrappers-dev
datomic-local
emacs-dev
activemq-mysql-prod
build-build
release-5.5
mutt
...An example of common usage in a pipeline is to use screen-ls to find a given screen(1) session, and then use the shell's command recall and command line editing facilities to feed that found screen(1) session name to screen(1) in order to reconnect to it. Using our running example, let's say we want to reconnect to the screen(1) session in which emacs development is underway. In a POSIX compatible shell, that can be accomplished thus:
$ screen-ls | grep emacs
emacs-dev
$ screen -d -r $(screen-ls | grep emacs)Using bash(1), the keystrokes required for that invocation on the author's machine are:
s c r TAB - l TAB | g r e p SPACE e m a c s RET
C-p C-a s c r TAB - d SPACE - r SPACE $ ( C-e ) RETWhile that may be tedious to read, it flies off the fingers. Compare that to accomplishing the same task reliably without screen-ls.
If you have duplicate session names, in order to reconnect to a particular screen(1) session you will need to specify the pid prefix for the session name that screen-ls suppresses by default. You can prevent screen-ls from suppressing this behavior by specifying the -p (--show-pid) option:
$ screen-ls -p -U
779.screen-wrappers-dev
713.screen-wrappers-dev
26043.datomic-local
14926.emacs-dev
24078.activemq-mysql-prod
803.build-build
12522.release-5.5
5200.mutt
...
$ screen -d -r 713.screen-wrappers-devWhen invoked with the -l (--long) option, screen-ls will print the screen ls output in a readable table (still sorted by screen(1) session name):
$ screen-ls -l
activemq-mysql-prod (06/23/2013 01:22:41 AM) (Detached)
build-build (05/22/2013 06:02:49 AM) (Detached)
datomic-local (07/07/2013 02:20:50 PM) (Attached)
emacs-dev (06/30/2013 07:57:14 PM) (Attached)
mutt (05/17/2013 10:21:59 AM) (Attached)
release-5.5 (05/18/2013 06:09:31 AM) (Attached)
screen-wrappers-dev (07/08/2013 01:09:19 PM) (Attached)
...Of course, to see the pid prefixes on the session names, you would need to add the -p option to that:
$ screen-ls -l -p
24078.activemq-mysql-prod (06/23/2013 01:22:41 AM) (Detached)
803.build-build (05/22/2013 06:02:49 AM) (Detached)
26043.datomic-local (07/07/2013 02:20:50 PM) (Attached)
14926.emacs-dev (06/30/2013 07:57:14 PM) (Attached)
5200.mutt (05/17/2013 10:21:59 AM) (Attached)
12522.release-5.5 (05/18/2013 06:09:31 AM) (Attached)
779.screen-wrappers-dev (07/08/2013 01:09:19 PM) (Attached)
...Note that the output is still sorted by the screen(1) session name (as it exists without the '<pid>.' prefix, the same way you would see it within screen(1) when output via screen's sessionname command).
Exits with 0 (zero) status on success, nonzero on error.
Internally checks that the exit status of screen -ls is 1 when it detects that the underlying screen version is older than 4.0.3 (released 2015-06-12, advertized as 4.03.00 by screen --version). Those older versions have a bug that causes the screen -ls command to exit with status 1 upon success even when existing screen sessions are detected.
For info on the upstream bug see:
<http://savannah.gnu.org/bugs/?26750>See comments in screen-ls source code for more details (HINT: grep for SCREEN_LS_ESTAT).
If you find any others, please send a bug report to the author. See "AUTHOR"
Written by Alan D. Salewski <salewski@att.net>.
John Marquart (jomarqua@gmail.com)Copyright (C) 2013, 2016, 2017, 2019 Alan D. Salewski <salewski@att.net>
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.