lgrpinfo(1)							   User Commands						       lgrpinfo(1)

NAME

       lgrpinfo - display information about locality groups

SYNOPSIS

       lgrpinfo [-aceGlLmrt] [-u unit] [-C | -P] lgrp ...

       lgrpinfo -h

       lgrpinfo -I [-c] [-G] [-C | -P] lgrp ...

       lgrpinfo [-T] [-aceGlLmr] [-u unit]

DESCRIPTION

       lgrpinfo prints information about the locality group (lgroup) hierarchy and its contents.

       An  lgroup  represents  the set of CPU and memory-like hardware devices that are at most some distance (latency) apart from each other. All
       lgroups in the system are identified by a unique integer called an lgroup ID.

       lgroups are organized into a hierarchy to facilitate finding the nearest resources. Leaf lgroups each contain a set of resources  that  are
       closest	(local)  to  each  other.  Each parent lgroup in the hierarchy contains the resources of its child lgroups plus their next nearest
       resources. Finally, the root lgroup contains all the resources in the domain within the largest latency.

       A Uniform Memory Access (UMA) machine is simply represented by the root lgroup. A Non Uniform Memory Access (NUMA) machine  is  represented
       by  a  hierarchy of lgroups to show the corresponding levels of locality. For example, a NUMA machine with two latencies (local and remote)
       has an lgroup hierarchy consisting of two levels with its leaves and the root.

       Every application thread is assigned a home lgroup. When the system needs to allocate a CPU or memory resource for a  thread,  it  searches
       lgroup hierarchy from the thread's home lgroup for the closest available resources to the thread's home. See plgrp(1) for details.

       Without	arguments,  lgrpinfo  prints  general  information about all lgroups in the system. If any lgroup IDs are specified on the command
       line, the command only prints information about the specified lgroups. Various options control which lgroups are displayed  and	the  exact
       information that is printed for each lgroup.

       lgroups can be specified on the command line as lgroup IDs or by using specific keywords. See OPERANDS.

OPTIONS

       You  can  combine options together and the order in which options are specified is not important. Lowercase options select what information
       should be printed about lgroups.

       Invoking lgrpinfo without arguments is equivalent to:

	 lgrpinfo -c -e -l -m -r -t all

       The following options are supported:

       -a	   Print topology, CPU, memory, load and latency information.

		   This option is a shorthand for

		     lgrpinfo -t -c -e -m -r -l -L

		   unless -T is specified as well. When -T is specified, the -t option is not included.

       -c	   Print CPU information.

		   This is the default.

       -C	   Replace each lgroup in the list with its children.

		   This option cannot be used with the -P or the -T option. When no arguments are specified, this option is applied to the lgroups
		   displayed by default.

       -e	   Print lgroup load average. The lgroup load averages are only displayed for leaf lgroups.

		   This is the default.

       -G	   Print OS view of lgroup hierarchy.

		   By  default,  the  caller's view of the lgroup hierarchy is displayed which only includes what the caller can use, for example,
		   only the CPUs in the caller's processor set is displayed. See lgrp_init(3LGRP) on the operating system and the caller's view.

       -h	   Print short help message and exit.

       -I	   Print matching IDs only.

		   This option is intended for scripts and can be used with -c, -G, and -C or -P. If -c is specified, print list of CPUs contained
		   in all matching lgroups. Otherwise, the IDs for the matching lgroups is displayed. See EXAMPLES.

		   When no arguments are specified, this option is applied to the lgroups displayed, which, by default is all lgroups.

       -l	   Print information about lgroup latencies.

		   The	latency  value	specified for each lgroup is defined by the operating system and is platform-specific. It can only be used
		   for relative comparison of lgroups on the running system. It does not necessarily represent the actual latency between hardware
		   devices and might not be applicable across platforms.

       -L	   Print  the  lgroup  latency table. The lgroup latency table displays the relative latency from each lgroup to each of the other
		   lgroups including itself.

       -m	   Print memory information.

		   Memory sizes are scaled to the unit of measure that yields an integer from 0 to 1023 unless the -u option is specified as well.
		   The	fractional  part of the number is only displayed for values less than 10. This behavior is similiar to using the -h option
		   of ls(1) or df(1M) to display a human readable format.

		   This is the default.

       -P	   Replace each lgroup in the list with its parents.

		   This option cannot be used with the -C or -T option. When no arguments are specified, this option is  applied  to  the  lgroups
		   displayed, which, by default is all lgroups.

       -r	   Print information about lgroup resources.

		   The resources are represented by a set of lgroups in which each member lgroup directly contains CPU and memory resources. If -T
		   is specified as well, only information about resources of the intermediate lgroups is displayed.

       -t	   Print information about lgroup topology.

		   This is the default.

       -T	   Print the lgroup topology of a system graphically as a tree. This option can only be used with the -a, -c, -e, -G,  -l,-L,  -m,
		   -r,	and  -u  options. It only prints lgroup resources for intermediate lgroups when used with the -r. The -t option is omitted
		   when -T is used with -a. No information is printed for the root lgroup unless it is the only lgroup.

       -u units    Specify memory units. Units should be b, k, m, g, t, p, or e for bytes, kilobytes, megabytes, gigabytes, terabytes,	petabytes,
		   or  exabytes respectively. The fractional part of the number is only displayed for values less than 10. This behavior is simil-
		   iar to using the -h option of ls(1) or df(1M) to display a human readable format.

OPERANDS

       The following operands are supported:

       lgrp    lgroups can be specified on the command line as lgroup ID, by using one of the following keywords:

	       all	       All lgroups.

			       This is the default.

	       intermediate    All intermediate lgroups. An intermediate lgroup is an lgroup that has a parent and children.

	       leaves	       All leaf lgroups. A leaf lgroup is an lgroup that has no children in the lgroup hierarchy.

	       root	       Root lgroup. Root lgroup contains all the resources in the domain within the largest  latency  and  has	no  parent
			       lgroup.

       If  an invalid lgroup is specified, the lgrpinfo command prints a message on standard error showing the invalid ID and continues processing
       other lgroups specified on the command line. When none of the specified lgroups are valid, lgrpinfo exits with an exit status of 2.

EXAMPLES

       Example 1 Printing Information about lgroups

       The following example prints general information about lgroups in the system.

       In this example, the system is a 2 CPU AMD Opteron machine with two nodes, each having one CPU and 2 gigabytes of  memory.  Each  of  these
       nodes is represented by a leaf lgroup. The root lgroup contains all the resources in the machine:

	 $ lgrpinfo
	   lgroup 0 (root):
		   Children: 1 2
		   CPUs: 0 1
		   Memory: installed 4.0G, allocated 2.2G, free 1.8G
		   Lgroup resources: 1 2 (CPU); 1 2 (memory)
		   Latency: 83
	   lgroup 1 (leaf):
		   Children: none, Parent: 0
		   CPU: 0
		   Memory: installed 2.0G, allocated 1.2G, free 788M
		   Lgroup resources: 1 (CPU); 1 (memory)
		   Load: 0.793
		   Latency: 56
	   lgroup 2 (leaf):
		   Children: none, Parent: 0
		   CPU: 1
		   Memory: installed 2.0G, allocated 1017M, free 1.0G
		   Lgroup resources: 2 (CPU); 2 (memory)
		   Load: 0.817
		   Latency: 56

       Example 2 Printing lgroup Topology

       The following example prints the lgroup topology tree on a 4 CPU AMD Opteron machine:

	 $ lgrpinfo -T
	   0
	   |-- 5
	   |   `-- 1
	   |-- 6
	   |   `-- 2
	   |-- 7
	   |   `-- 3
	   `-- 8
	       `-- 4

       Example 3 Printing lgroup Topology

       The following example prints the lgroup topology tree, resources, memory and CPU information on a 2 CPU AMD Opteron machine:

	 $ lgrpinfo -Ta
	   0
	   |-- 1
	   |   CPU: 0
	   |   Memory: installed 2.0G, allocated 1.2G, free 790M
	   |   Load: 0.274
	   |   Latency: 56
	   `-- 2
	       CPU: 1
	       Memory: installed 2.0G, allocated 1019M, free 1.0G
	       Load: 0.937
	       Latency: 56

	 Lgroup latencies:

	 ------------
	     |	0  1  2
	   ------------
	   0 | 83 83 83
	   1 | 83 56 83
	   2 | 83 83 56
	   ------------

       Example 4 Printing lgroup IDs

       The following example prints lgroup IDs for children of the root lgroup:

	 $ lgrpinfo -I -C root
	   1 2

       Example 5 Printing CPU IDs

       The following example prints CPU IDs for all CPUs in lgroup 1:

	 $ lgrpinfo -c -I 1
	   0

       Example 6 Printing Information about lgropu Latencies

       The following example prints information about lgroup latencies:

	  $ lgrpinfo -l
	   lgroup 0 (root):
		   Latency: 83
	   lgroup 1 (leaf):
		   Latency: 56
	   lgroup 2 (leaf):
		   Latency: 5

EXIT STATUS

       The following exit values are returned:

       0    Successful completion.

       1    Unable to get lgroup information from the system.

       2    All lgroups specified are invalid.

       3    Invalid syntax.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWesu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+

       The human readable output is Unstable.

SEE ALSO

       ls(1), plgrp(1), pmap(1), proc(1), ps(1), df(1M), prstat(1M), lgrp_init(3LGRP), liblgrp(3LIB), proc(4), attributes(5)

SunOS 5.11							    11 Sep 2006 						       lgrpinfo(1)