'\"macro stdmacro
.\"
.\" Copyright (c) 2014,2019-2020 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PCP-FREE 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pcp-free\f1 \- report on free and used memory in the system
.SH SYNOPSIS
\f3pcp\f1
[\f2pcp\ options\f1]
\f3free\f1
[\f3\-bkmgroltVw?\f1]
[\f3\-c\f1 \f2count\f1]
[\f3\-s\f1 \f2interval\f1]
.SH DESCRIPTION
.B pcp-free
gives a summary display of the total amount of free and used
physical memory and swap in the system, as well as the caches
used by the kernel.
.PP
When invoked via the
.BR pcp (1)
command, the
.BR \-h /\c
.BR \-\-host ,
.BR \-a /\c
.BR \-\-archive ,
.BR \-O /\c
.BR \-\-origin ,
.BR \-s /\c
.BR \-\-samples ,
.BR \-t /\c
.BR \-\-interval ,
.BR \-Z /\c
.BR \-\-timezone
and several other
.B pcp
.I options
become indirectly available, see
.BR PCPIntro (1)
for their descriptions.
.PP
The displayed columns are:
.TP
\fBtotal\fR
Total installed memory (MemTotal and SwapTotal in /proc/meminfo)
.TP
\fBused\fR
Used memory (calculated as \fBtotal\fR - \fBfree\fR - \fBbuffers\fR - \fBcache\fR)
.TP
\fBfree\fR
Unused memory (MemFree and SwapFree in /proc/meminfo)
.TP
\fBshared\fR
Memory used (mostly) by tmpfs (Shmem in /proc/meminfo)
.TP
\fBbuffers\fR
Memory used by kernel buffers (Buffers in /proc/meminfo)
.TP
\fBcache\fR
Memory used by the page cache and slabs (Cached and SReclaimable in /proc/meminfo)
.TP
\fBbuff/cache\fR
Sum of \fBbuffers\fR and \fBcache\fR
.TP
\fBavailable\fR
Estimation of how much memory is available for starting
new applications, without swapping.
Unlike the data provided by the \fBcache\fR or \fBfree\fR
fields, this field takes into account page cache and also
that not all reclaimable memory slabs will be reclaimed
due to items being in use (MemAvailable in /proc/meminfo).
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-b\fP, \fB\-\-bytes\fP
Display the amount of memory in bytes.
.TP
\fB\-c\fR \fIcount\fR, \fB\-\-samples\fR=\fIcount\fR
Terminate the display after \fIcount\fR iterations.
See also
.BR \-s .
.TP
\fB\-g\fP, \fB\-\-gigabytes\fP
Display the amount of memory in gigabytes.
.TP
\fB\-k\fP, \fB\-\-kilobytes\fP
Display the amount of memory in kilobytes.
This is the default.
.TP
\fB\-l\fP
Display detailed low and high memory statistics.
.TP
\fB\-m\fP, \fB\-\-megabytes\fP
Display the amount of memory in megabytes.
.TP
\fB-o\fP
Disable the display of a "buffer adjusted" line.
If the \fB-o\fP option is not specified, \fBfree\fP subtracts buffer memory
from the used memory and adds it to the free memory reported.
.TP
\fB\-r\fP, \fB\-\-terabytes\fP
Display the amount of memory in terabytes.
.TP
\fB\-s\fR \fIdelay\fR, \fB\-\-interval\fR=\fIdelay\fR
Activate continuous polling \fIdelay\fP seconds apart.
You may specify any floating point number for \fIdelay\fP, or indeed any valid
.BR pmParseInterval (3)
specification, which includes microsecond resolution delay times.
This can be used in conjunction with the \fB\-c\fP option.
.TP
\fB\-t\fP, \fB\-\-total\fP
Display a line containing the totals.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
.TP
\fB\-w\fR, \fB\-\-wide\fR
Switch to the wide mode.
The wide mode produces lines longer than 80 characters.
In this mode \fBbuffers\fR and \fBcache\fR are reported
in two separate columns.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH NOTES
.B pcp-free
is inspired by the
.BR free (1)
command and aims to be command line and output compatible with it.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pcp (1),
.BR free (1),
.BR pmParseInterval (3)
and
.BR environ (7).