-.\" Process this file with
-.\" groff -man -Tascii lscpu.1
-.\"
-.TH LSCPU 1 "February 2011" "util-linux" "User Commands"
+.TH LSCPU 1 "March 2019" "util-linux" "User Commands"
.SH NAME
-lscpu \- display information on CPU architecture
+lscpu \- display information about the CPU architecture
.SH SYNOPSIS
.B lscpu
-.RB [ \-ehpxV ]
-.RB [ \-s
-.IR directory ]
+[options]
.SH DESCRIPTION
.B lscpu
-gathers CPU architecture information like number of CPUs, threads,
-cores, sockets, NUMA nodes, information about CPU caches, CPU family,
-model, bogoMIPS, byte order and stepping from sysfs and /proc/cpuinfo, and prints it in
-a human-readable format. It supports both online and offline CPUs.
-It can also print out in a parsable format,
-including how different caches are shared by different CPUs,
-which can be fed to other programs.
+gathers CPU architecture information from sysfs, /proc/cpuinfo and any
+applicable architecture-specific libraries (e.g.\& librtas on Powerpc). The
+command output can be optimized for parsing or for easy readability by humans.
+The information includes, for example, the number of CPUs, threads, cores,
+sockets, and Non-Uniform Memory Access (NUMA) nodes. There is also information
+about the CPU caches and cache sharing, family, model, bogoMIPS, byte order,
+and stepping.
+.sp
+In virtualized environments, the CPU architecture information displayed
+reflects the configuration of the guest operating system which is
+typically different from the physical (host) system. On architectures that
+support retrieving physical topology information,
+.B lscpu
+also displays the number of physical sockets, chips, cores in the host system.
+.sp
+Options that result in an output table have a \fIlist\fP argument. Use this
+argument to customize the command output. Specify a comma-separated list of
+column labels to limit the output table to only the specified columns, arranged
+in the specified order. See \fBCOLUMNS\fP for a list of valid column labels. The
+column labels are not case sensitive.
+.sp
+Not all columns are supported on all architectures. If an unsupported column is
+specified, \fBlscpu\fP prints the column but does not provide any data for it.
+.sp
+The default output formatting on terminal maybe optimized for better
+readability. The output for non-terminals (e.g. pipes) is never affected by
+this optimization and it is always in "Field: data\\n" format.
+.SS COLUMNS
+Note that topology elements (core, socket, etc.) use a sequential unique ID
+starting from zero, but CPU logical numbers follow the kernel where there is
+no guarantee of sequential numbering.
+.TP
+.B CPU
+The logical CPU number of a CPU as used by the Linux kernel.
+.TP
+.B CORE
+The logical core number. A core can contain several CPUs.
+.TP
+.B SOCKET
+The logical socket number. A socket can contain several cores.
+.TP
+.B BOOK
+The logical book number. A book can contain several sockets.
+.TP
+.B DRAWER
+The logical drawer number. A drawer can contain several books.
+.TP
+.B NODE
+The logical NUMA node number. A node can contain several drawers.
+.TP
+.B CACHE
+Information about how caches are shared between CPUs.
+.TP
+.B ADDRESS
+The physical address of a CPU.
+.TP
+.B ONLINE
+Indicator that shows whether the Linux instance currently makes use of the CPU.
+.TP
+.B CONFIGURED
+Indicator that shows if the hypervisor has allocated the CPU to the virtual
+hardware on which the Linux instance runs. CPUs that are configured can be set
+online by the Linux instance.
+This column contains data only if your hardware system and hypervisor support
+dynamic CPU resource allocation.
+.TP
+.B POLARIZATION
+This column contains data for Linux instances that run on virtual hardware with
+a hypervisor that can switch the CPU dispatching mode (polarization). The
+polarization can be:
+.RS
+.TP 12
+.B horizontal\fP
+The workload is spread across all available CPUs.
+.TP 12
+.B vertical
+The workload is concentrated on few CPUs.
+.P
+For vertical polarization, the column also shows the degree of concentration,
+high, medium, or low. This column contains data only if your hardware system
+and hypervisor support CPU polarization.
+.RE
+.TP
+.B MAXMHZ
+Maximum megahertz value for the CPU. Useful when \fBlscpu\fP is used as hardware
+inventory information gathering tool. Notice that the megahertz value is
+dynamic, and driven by CPU governor depending on current resource need.
+.TP
+.B MINMHZ
+Minimum megahertz value for the CPU.
+.SH OPTIONS
+.TP
+.BR \-a , " \-\-all"
+Include lines for online and offline CPUs in the output (default for \fB-e\fR).
+This option may only be specified together with option \fB-e\fR or \fB-p\fR.
+.TP
+.BR \-B , " \-\-bytes"
+Print the sizes in bytes rather than in a human-readable format.
+.TP
+.BR \-b , " \-\-online"
+Limit the output to online CPUs (default for \fB-p\fR).
+This option may only be specified together with option \fB-e\fR or \fB-p\fR.
+.TP
+.BR \-C , " \-\-caches" [=\fIlist\fP]
+Display details about CPU caches. For details about available information see \fB\-\-help\fR
+output.
-Some options have a \fIlist\fP argument. The \fIlist\fP argument is a comma
-delimited list of the columns. Currently supported are CPU, Core, Node, Socket,
-Book, Cache, Polarization and Address columns.
-If the \fIlist\fP argument is given then all requested columns are printed in
-the defined order.
+If the \fIlist\fP argument is omitted, all columns for which data is available
+are included in the command output.
-.SH OPTIONS
+When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
+\fIlist\fP must not contain any blanks or other whitespace.
+Examples: '\fB-C=NAME,ONE-SIZE\fP' or '\fB--caches=NAME,ONE-SIZE\fP'.
.TP
+.BR \-c , " \-\-offline"
+Limit the output to offline CPUs.
+This option may only be specified together with option \fB-e\fR or \fB-p\fR.
.TP
-.BR \-e , " \-\-extended " \fI[=list]\fP
-Print CPU list out in human-readable format.
+.BR \-e , " \-\-extended" [=\fIlist\fP]
+Display the CPU information in human-readable format.
-If the \fIlist\fP argument is not given then all columns where data is
-available will be printed.
+If the \fIlist\fP argument is omitted, all columns for which data is available
+are included in the command output.
-Note that the optional \fIlist\fP argument cannot be separated from the
-option by a space, the correct form is for example '\fB-e=cpu,node\fP' or '\fB--extended=cpu,node\fP'.
+When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
+\fIlist\fP must not contain any blanks or other whitespace.
+Examples: '\fB-e=cpu,node\fP' or '\fB--extended=cpu,node\fP'.
.TP
.BR \-h , " \-\-help"
-Print a help message.
+Display help text and exit.
+.TP
+.BR \-J , " \-\-json"
+Use JSON output format for the default summary or extended output (see \fB\-\-extended\fP).
.TP
-.BR \-p , " \-\-parse " \fI[=list]\fP
-Print out in parsable format.
+.BR \-p , " \-\-parse" [=\fIlist\fP]
+Optimize the command output for easy parsing.
-If the \fIlist\fP argument is not given then the default backwardly compatible
-output is printed. The backwardly compatible format uses two commas to
-separate CPU cache columns. If no CPU caches are identified, then the cache
-columns are not printed at all.
+If the \fIlist\fP argument is omitted, the command output is compatible with earlier
+versions of \fBlscpu\fP. In this compatible format, two commas are used to separate
+CPU cache columns. If no CPU caches are identified the cache column is omitted.
.br
-If the \fIlist\fP argument is given then the cache columns are separated by ':'.
+If the \fIlist\fP argument is used, cache columns are separated with a colon (:).
-Note that the optional \fIlist\fP argument cannot be separated from the
-option by a space, the correct form is for example '\fB-p=cpu,node\fP' or '\fB--parse=cpu,node\fP'.
+When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
+\fIlist\fP must not contain any blanks or other whitespace.
+Examples: '\fB-p=cpu,node\fP' or '\fB--parse=cpu,node\fP'.
.TP
.BR \-s , " \-\-sysroot " \fIdirectory\fP
-Use the specified \fIdirectory\fP as system root. This allows you to inspect
-a snapshot from a different system.
+Gather CPU data for a Linux instance other than the instance from which the
+\fBlscpu\fP command is issued. The specified \fIdirectory\fP is the system root
+of the Linux instance to be inspected.
.TP
.BR \-x , " \-\-hex"
-Use hexadecimal masks for CPU sets (e.g. 0x3). The default is to print the sets
-in list format (e.g. 0,1).
+Use hexadecimal masks for CPU sets (for example "ff"). The default is to print
+the sets in list format (for example 0,1). Note that before version 2.30 the mask
+has been printed with 0x prefix.
+.TP
+.BR \-y , " \-\-physical"
+Display physical IDs for all columns with topology elements (core, socket, etc.).
+Other than logical IDs, which are assigned by \fBlscpu\fP, physical IDs are
+platform-specific values that are provided by the kernel. Physical IDs are not
+necessarily unique and they might not be arranged sequentially.
+If the kernel could not retrieve a physical ID for an element \fBlscpu\fP prints
+the dash (-) character.
+
+The CPU logical numbers are not affected by this option.
.TP
.BR \-V , " \-\-version"
-Output version information and exit.
+Display version information and exit.
+.TP
+.B \-\-output\-all
+Output all available columns. This option must be combined with either
+.BR \-\-extended ", " \-\-parse " or " \-\-caches .
.SH BUGS
-The basic overview about CPU family, model, etc. is always based on the first
+The basic overview of CPU family, model, etc. is always based on the first
CPU only.
Sometimes in Xen Dom0 the kernel reports wrong data.
+
+On virtual hardware the number of cores per socket, etc. can be wrong.
.SH AUTHOR
.nf
Cai Qian <qcai@redhat.com>
Karel Zak <kzak@redhat.com>
+Heiko Carstens <heiko.carstens@de.ibm.com>
.fi
.SH "SEE ALSO"
-.BR chcpu (1)
+.BR chcpu (8)
.SH AVAILABILITY
The lscpu command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+https://www.kernel.org/pub/linux/utils/util-linux/.
projects / thirdparty / util-linux.git / blobdiff