'\" t
.\"     Title: perf-buildid-cache
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 11/12/2025
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF\-BUILDID\-CACHE" "1" "11/12/2025" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-buildid-cache \- Manage build\-id cache\&.
.SH "SYNOPSIS"
.sp
.nf
\fIperf buildid\-cache <options>\fR
.fi
.SH "DESCRIPTION"
.sp
This command manages the build\-id cache\&. It can add, remove, update and purge files to/from the cache\&. In the future it should as well set upper limits for the space used by the cache, etc\&. This also scans the target binary for SDT (Statically Defined Tracing) and record it along with the buildid\-cache, which will be used by perf\-probe\&. For more details, see \fBperf-probe\fR(1)\&.
.SH "OPTIONS"
.PP
\-a, \-\-add=
.RS 4
Add specified file to the cache\&.
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt complain, do it\&.
.RE
.PP
\-k, \-\-kcore
.RS 4
Add specified kcore file to the cache\&. For the current host that is /proc/kcore which requires root permissions to read\&. Be aware that running
\fIperf buildid\-cache\fR
as root may update root\(cqs build\-id cache not the user\(cqs\&. Use the \-v option to see where the file is created\&. Note that the copied file contains only code sections not the whole core image\&. Note also that files "kallsyms" and "modules" must also be in the same directory and are also copied\&. All 3 files are created with read permissions for root only\&. kcore will not be added if there is already a kcore in the cache (with the same build\-id) that has the same modules at the same addresses\&. Use the \-v option to see if a copy of kcore is actually made\&.
.RE
.PP
\-r, \-\-remove=
.RS 4
Remove a cached binary which has same build\-id of specified file from the cache\&.
.RE
.PP
\-p, \-\-purge=
.RS 4
Purge all cached binaries including older caches which have specified path from the cache\&.
.RE
.PP
\-P, \-\-purge\-all
.RS 4
Purge all cached binaries\&. This will flush out entire cache\&.
.RE
.PP
\-M, \-\-missing=
.RS 4
List missing build ids in the cache for the specified file\&.
.RE
.PP
\-u, \-\-update=
.RS 4
Update specified file of the cache\&. Note that this doesn\(cqt remove older entries since those may be still needed for annotating old (or remote) perf\&.data\&. Only if there is already a cache which has exactly same build\-id, that is replaced by new one\&. It can be used to update kallsyms and kernel dso to vmlinux in order to support annotation\&.
.RE
.PP
\-l, \-\-list
.RS 4
List all valid binaries from cache\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose\&.
.RE
.sp
\-\-target\-ns=PID: Obtain mount namespace information from the target pid\&. This is used when creating a uprobe for a process that resides in a different mount namespace from the perf(1) utility\&.
.PP
\-\-debuginfod=URLs
.RS 4
Specify debuginfod URL to be used when retrieving perf\&.data binaries, it follows the same syntax as the DEBUGINFOD_URLS variable, like:
.sp
.if n \{\
.RS 4
.\}
.nf
buildid\-cache\&.debuginfod=http://192\&.168\&.122\&.174:8002
.fi
.if n \{\
.RE
.\}
.RE
.SH "SEE ALSO"
.sp
\fBperf-record\fR(1), \fBperf-report\fR(1), \fBperf-buildid-list\fR(1)