]> git.ipfire.org Git - thirdparty/util-linux.git/blob - sys-utils/lscpu.1
lscpu: document --hex output regression (since v2.30)
[thirdparty/util-linux.git] / sys-utils / lscpu.1
1 .TH LSCPU 1 "November 2015" "util-linux" "User Commands"
2 .SH NAME
3 lscpu \- display information about the CPU architecture
4 .SH SYNOPSIS
5 .B lscpu
6 .RB [ \-a | \-b | \-c | \-J "] [" \-x "] [" \-y "] [" \-s " \fIdirectory\fP] [" \-e [=\fIlist\fP]| \-p [=\fIlist\fP]]
7 .br
8 .B lscpu
9 .BR \-h | \-V
10 .SH DESCRIPTION
11 .B lscpu
12 gathers CPU architecture information from sysfs, /proc/cpuinfo and any
13 applicable architecture-specific libraries (e.g.\& librtas on Powerpc). The
14 command output can be optimized for parsing or for easy readability by humans.
15 The information includes, for example, the number of CPUs, threads, cores,
16 sockets, and Non-Uniform Memory Access (NUMA) nodes. There is also information
17 about the CPU caches and cache sharing, family, model, bogoMIPS, byte order,
18 and stepping.
19 .sp
20 In virtualized environments, the CPU architecture information displayed
21 reflects the configuration of the guest operating system which is
22 typically different from the physical (host) system. On architectures that
23 support retrieving physical topology information,
24 .B lscpu
25 also displays the number of physical sockets, chips, cores in the host system.
26 .sp
27 Options that result in an output table have a \fIlist\fP argument. Use this
28 argument to customize the command output. Specify a comma-separated list of
29 column labels to limit the output table to only the specified columns, arranged
30 in the specified order. See \fBCOLUMNS\fP for a list of valid column labels. The
31 column labels are not case sensitive.
32 .sp
33 Not all columns are supported on all architectures. If an unsupported column is
34 specified, \fBlscpu\fP prints the column but does not provide any data for it.
35
36 .SS COLUMNS
37 Note that topology elements (core, socket, etc.) use a sequential unique ID
38 starting from zero, but CPU logical numbers follow the kernel where there is
39 no guarantee of sequential numbering.
40 .TP
41 .B CPU
42 The logical CPU number of a CPU as used by the Linux kernel.
43 .TP
44 .B CORE
45 The logical core number. A core can contain several CPUs.
46 .TP
47 .B SOCKET
48 The logical socket number. A socket can contain several cores.
49 .TP
50 .B BOOK
51 The logical book number. A book can contain several sockets.
52 .TP
53 .B DRAWER
54 The logical drawer number. A drawer can contain several books.
55 .TP
56 .B NODE
57 The logical NUMA node number. A node can contain several drawers.
58 .TP
59 .B CACHE
60 Information about how caches are shared between CPUs.
61 .TP
62 .B ADDRESS
63 The physical address of a CPU.
64 .TP
65 .B ONLINE
66 Indicator that shows whether the Linux instance currently makes use of the CPU.
67 .TP
68 .B CONFIGURED
69 Indicator that shows if the hypervisor has allocated the CPU to the virtual
70 hardware on which the Linux instance runs. CPUs that are configured can be set
71 online by the Linux instance.
72 This column contains data only if your hardware system and hypervisor support
73 dynamic CPU resource allocation.
74 .TP
75 .B POLARIZATION
76 This column contains data for Linux instances that run on virtual hardware with
77 a hypervisor that can switch the CPU dispatching mode (polarization). The
78 polarization can be:
79 .RS
80 .TP 12
81 .B horizontal\fP
82 The workload is spread across all available CPUs.
83 .TP 12
84 .B vertical
85 The workload is concentrated on few CPUs.
86 .P
87 For vertical polarization, the column also shows the degree of concentration,
88 high, medium, or low. This column contains data only if your hardware system
89 and hypervisor support CPU polarization.
90 .RE
91 .TP
92 .B MAXMHZ
93 Maximum megahertz value for the CPU. Useful when \fBlscpu\fP is used as hardware
94 inventory information gathering tool. Notice that the megahertz value is
95 dynamic, and driven by CPU governor depending on current resource need.
96 .TP
97 .B MINMHZ
98 Minimum megahertz value for the CPU.
99 .SH OPTIONS
100 .TP
101 .BR \-a , " \-\-all"
102 Include lines for online and offline CPUs in the output (default for \fB-e\fR).
103 This option may only be specified together with option \fB-e\fR or \fB-p\fR.
104 .TP
105 .BR \-b , " \-\-online"
106 Limit the output to online CPUs (default for \fB-p\fR).
107 This option may only be specified together with option \fB-e\fR or \fB-p\fR.
108 .TP
109 .BR \-c , " \-\-offline"
110 Limit the output to offline CPUs.
111 This option may only be specified together with option \fB-e\fR or \fB-p\fR.
112 .TP
113 .BR \-e , " \-\-extended" [=\fIlist\fP]
114 Display the CPU information in human-readable format.
115
116 If the \fIlist\fP argument is omitted, all columns for which data is available
117 are included in the command output.
118
119 When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
120 \fIlist\fP must not contain any blanks or other whitespace.
121 Examples: '\fB-e=cpu,node\fP' or '\fB--extended=cpu,node\fP'.
122 .TP
123 .BR \-h , " \-\-help"
124 Display help text and exit.
125 .TP
126 .BR \-J , " \-\-json"
127 Use JSON output format for the default summary or extended output (see \fB\-\-extended\fP).
128 .TP
129 .BR \-p , " \-\-parse" [=\fIlist\fP]
130 Optimize the command output for easy parsing.
131
132 If the \fIlist\fP argument is omitted, the command output is compatible with earlier
133 versions of \fBlscpu\fP. In this compatible format, two commas are used to separate
134 CPU cache columns. If no CPU caches are identified the cache column is omitted.
135 .br
136 If the \fIlist\fP argument is used, cache columns are separated with a colon (:).
137
138 When specifying the \fIlist\fP argument, the string of option, equal sign (=), and
139 \fIlist\fP must not contain any blanks or other whitespace.
140 Examples: '\fB-p=cpu,node\fP' or '\fB--parse=cpu,node\fP'.
141 .TP
142 .BR \-s , " \-\-sysroot " \fIdirectory\fP
143 Gather CPU data for a Linux instance other than the instance from which the
144 \fBlscpu\fP command is issued. The specified \fIdirectory\fP is the system root
145 of the Linux instance to be inspected.
146 .TP
147 .BR \-x , " \-\-hex"
148 Use hexadecimal masks for CPU sets (for example "ff"). The default is to print
149 the sets in list format (for example 0,1). Note that before version 2.30 the mask
150 has been printed with 0x prefix.
151 .TP
152 .BR \-y , " \-\-physical"
153 Display physical IDs for all columns with topology elements (core, socket, etc.).
154 Other than logical IDs, which are assigned by \fBlscpu\fP, physical IDs are
155 platform-specific values that are provided by the kernel. Physical IDs are not
156 necessarily unique and they might not be arranged sequentially.
157 If the kernel could not retrieve a physical ID for an element \fBlscpu\fP prints
158 the dash (-) character.
159
160 The CPU logical numbers are not affected by this option.
161 .TP
162 .BR \-V , " \-\-version"
163 Display version information and exit.
164 .TP
165 .B \-\-output\-all
166 Output all available columns. This option must be combined with either
167 .BR \-\-extended " or " \-\-parse .
168 .SH BUGS
169 The basic overview of CPU family, model, etc. is always based on the first
170 CPU only.
171
172 Sometimes in Xen Dom0 the kernel reports wrong data.
173
174 On virtual hardware the number of cores per socket, etc. can be wrong.
175 .SH AUTHOR
176 .nf
177 Cai Qian <qcai@redhat.com>
178 Karel Zak <kzak@redhat.com>
179 Heiko Carstens <heiko.carstens@de.ibm.com>
180 .fi
181 .SH "SEE ALSO"
182 .BR chcpu (8)
183 .SH AVAILABILITY
184 The lscpu command is part of the util-linux package and is available from
185 https://www.kernel.org/pub/linux/utils/util-linux/.