.Dd July 10, 2025
.Dt GCORE 1
.Os Darwin
.Sh NAME
.Nm gcore
.Nd get a core image of a running process
.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl s
.Op Fl b Ar size
.Op Fl x Ar content
.Op Fl o Ar path | Fl c Ar pathformat
.Ar pid
.Sh DESCRIPTION
The
.Nm gcore
program creates a core file image of the process specified by
.Ar pid .
The resulting core file can be used with a debugger, e.g.
.Xr lldb 1 ,
to examine the state of the process.
.Pp
The following options are available:
.Bl -tag -width Fl
.It Fl s
Suspend the process while the core file is captured.
.It Fl v
Report progress on the dump as it proceeds.
.It Fl b Ar size
Limit the size of the core file to
.Ar size
MiBytes.
.It Fl x Ar content
Select the content type of process pages written to the core file.
The currently supported content types are:
.Bl -tag -width compact
.It Cm stack
Only include pages containing stack regions.
.It Cm compact
Only include pages that were modified during execution.
.It Cm full
All accessible pages in the process.
.Pp
.El
The
.Ar full
content option is the default, and may lead to the creation of
very large core files.
The
.Ar stack
content type can be useful to examine low-level thread stacks.
The resulting core file is small, but the
amount of debugging information that is available is
correspondingly limited.
The
.Ar compact
content setting produces core files that are usually smaller than the
.Ar full
option.
.El
.El
.Pp
The following options control the name of the core file:
.Bl -tag -width flag
.It Fl o Ar path
Write the core file to
.Ar path .
.It Fl c Ar pathformat
Write the core file to
.Ar pathformat .
The
.Ar pathformat
string is treated as a pathname that may contain various special
characters which cause the interpolation of strings representing
specific attributes of the process into the name.
.Pp
Each special character is introduced by the
.Cm %
character.
The format characters and their meanings are:
.Bl -tag -width Fl
.It Cm N
The name of the program being dumped, as reported by
.Xr ps 1 .
.It Cm U
The uid of the process being dumped, converted to a string.
.It Cm G
The gid of the process being dumped, converted to a string.
.It Cm P
The pid of the process being dumped, converted to a string.
.It Cm T
The time when the core file was created, converted to ISO 8601 format.
.It Cm t
The time when the core file was created, converted to seconds since the epoch.
.It Cm H
The hostname of the system, determined from the
.Ar kern.hostname
MIB.
.It Cm %
Output a percent character.
.El
.El
.Pp
The default file name used by
.Nm
is
.Ar %N-%P-%T .
By default, the core file will be written to a directory whose
name is determined from the
.Ar kern.corefile
MIB.
This can be printed or modified using
.Xr sysctl 8 .
.Pp
The directory where the core file is to be written must be
accessible to the owner of the target process.
.Pp
.Nm
will not overwrite an existing file,
nor will it create missing directories in the path.
.Sh FILES
.Bl -tag -width "/cores/%N-%P-%T plus" -compact
.It Pa /cores/%N-%P-%T
default pathname for the corefile.
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr lldb 1 ,
.Xr otool 1 ,
.Xr core 5 ,
.Xr Mach-O 5 ,
.Xr sudo 8 ,
.Xr sysctl 8
.Sh CAVEATS
By default,
.Nm
uses a copy-on-write address space snapshot to dump a process, minimizing
the time that the process is unable to respond to external events.
However, these snapshots are a limited resource, and if it cannot
be taken,
.Nm
will revert to the historical behavior of
.Nm
i.e. it will capture the state of the process without suspending its
execution, which may result in an inconsistent
state being saved to the resulting core file.
Use the
.Fl s
flag if this is a concern.
.Pp
For both
.Ar stack
and
.Ar compact
content options it is important to realize that the resulting core file
is reduced in size because it implicitly refers to the contents of the
application together with its library and framework dependencies that were
present on the system at the specific point in time that the dump was taken.
As a result, such core files are most useful when debugging
applications on the same system that they were captured on.
Attempting to use those core files for debugging on a different
platform, or after any of the components have been updated, may
make productive debugging far more difficult.