lsmem: add --split

Now the way how lsmem lists memory ranges is affected by used output
columns.  It makes it very difficult to use in scripts where you want
to use for example only one column

	ranges=$(lsmem -oRANGE)

and in this case all is merged to the one (or two) huge ranges and all
attributes are ignored. The --split allows to control this behavior

	ranges=$(lsmem -oRANGE --split=STATE,ZONES)

forces lsmem to list ranges by STATE and ZONES differences.

Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 21 insertions, 6 deletions

diff --git a/sys-utils/lsmem.1 b/sys-utils/lsmem.1
index c664273f0..af65c2abb 100644
--- a/sys-utils/lsmem.1
+++ b/sys-utils/lsmem.1
@@ -10,19 +10,29 @@ status. The listed memory blocks correspond to the memory block representation
 in sysfs. The command also shows the memory block size and the amount of memory
 in online and offline state.
 
-The default output compatible with original implementaion from s390-tools, but
+The default output compatible with original implementation from s390-tools, but
 it's strongly recommended to avoid using default outputs in your scripts.
 Always explicitly define expected columns by using the \fB\-\-output\fR option
 together with a columns list in environments where a stable output is required.
 
+The \fBlsmem\fP command lists a new memory range always when the current memory
+block distinguish from the previous block by STATE, REMOVABLE, NODE or ZONES
+attribute.  This default behavior is possible to override by the
+\fB\-\-split\fR option (e.g. \fBlsmem \-\-split=STATE,ZONES\fR).  The special
+word "none" may be used to ignore all differences between memory blocks and to
+create as large as possible continuous ranges.  The opposite semantic is
+\fB\-\-all\fR to list individual memory blocks.  The default split policy is
+subject to change.  Always explicitly use \fB\-\-split\fR in environments where
+a stable output is required.
+
+Note that some output columns may provide inaccurate information if a split policy
+forces \fBlsmem\fP to ignore diffrences in some attributes. For example if you
+merge removable and non-removable memory blocks to the one range than all
+the range will be marked as non-removable on \fBlsmem\fP output.
+
 Not all columns are supported on all systems.  If an unsupported column is
 specified, \fBlsmem\fP prints the column but does not provide any data for it.
 
-The number of output entries (memory ranges) maybe be influenced by specified
-columns. The lsmem command shows larger memory ranges if the blocks in the
-range do not distinguish in output columns. For example RANGE maybe be
-different if the command output contains column ZONES (lsmem -o +ZONES).
-
 Use the \fB\-\-help\fR option to see the columns description.
 
 .SH OPTIONS
@@ -57,6 +67,11 @@ All potentially unsafe characters are hex-escaped (\\x<code>).
 Produce output in raw format.  All potentially unsafe characters are hex-escaped
 (\\x<code>).
 .TP
+.BR \-S , " \-\-split " \fIlist\fP
+Specify which columns (attributes) use to split memory blocks to ranges.  The
+supported columns are STATE, REMOVABLE, NODE and ZONES, or "none". The another columns are
+silently ignored. For more details see DESCRIPTION above.
+.TP
 .BR \-s , " \-\-sysroot " \fIdirectory\fP
 Gather memory data for a Linux instance other than the instance from which the
 \fBlsmem\fP command is issued.  The specified \fIdirectory\fP is the system