Changeset View
Changeset View
Standalone View
Standalone View
usr.bin/gcore/gcore.1
Show All 22 Lines | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | |||||||||
.\" | .\" | |||||||||
.\" @(#)gcore.1 8.2 (Berkeley) 4/18/94 | .\" @(#)gcore.1 8.2 (Berkeley) 4/18/94 | |||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | |||||||||
.\" | .\" | |||||||||
.Dd July 13, 2016 | .Dd April 24, 2021 | |||||||||
.Dt GCORE 1 | .Dt GCORE 1 | |||||||||
.Os | .Os | |||||||||
.Sh NAME | .Sh NAME | |||||||||
.Nm gcore | .Nm gcore | |||||||||
.Nd get core images of running process | .Nd get core images of running process | |||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | |||||||||
.Nm | .Nm | |||||||||
.Op Fl f | .Op Fl f | |||||||||
.Op Fl k | ||||||||||
.Op Fl c Ar core | .Op Fl c Ar core | |||||||||
.Op Ar executable | .Op Ar executable | |||||||||
.Ar pid | .Ar pid | |||||||||
emaste: I think convention is for non-arg flags to come first, all together? So `[-fk] [-c core]`? | ||||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | |||||||||
The | The | |||||||||
.Nm | .Nm | |||||||||
utility creates a core image of the specified process, | utility creates a core image of the specified process, | |||||||||
suitable for use with | suitable for use with | |||||||||
.Xr gdb 1 . | .Xr gdb 1 . | |||||||||
By default, the core is written to the file | By default, the core is written to the file | |||||||||
.Dq Pa core.<pid> . | .Dq Pa core.<pid> . | |||||||||
Show All 9 Lines | ||||||||||
.It Fl f | .It Fl f | |||||||||
Dumps all available segments, excluding only malformed and undumpable segments. | Dumps all available segments, excluding only malformed and undumpable segments. | |||||||||
Unlike the default invocation, this flag dumps mappings of devices which | Unlike the default invocation, this flag dumps mappings of devices which | |||||||||
may invalidate the state of device transactions or trigger other unexpected | may invalidate the state of device transactions or trigger other unexpected | |||||||||
behavior. | behavior. | |||||||||
As a result, this flag should only be used when the behavior of the | As a result, this flag should only be used when the behavior of the | |||||||||
application and any devices it has mapped is fully understood and any side | application and any devices it has mapped is fully understood and any side | |||||||||
effects can be controlled or tolerated. | effects can be controlled or tolerated. | |||||||||
.It Fl k | ||||||||||
Use the | ||||||||||
Done Inline ActionsProbably "Use the ptrace(2) PT_COREDUMP kernel facility to..." emaste: Probably "Use the ptrace(2) PT_COREDUMP kernel facility to..." | ||||||||||
.Xr ptrace 2 | ||||||||||
.Dv PT_COREDUMP | ||||||||||
kernel facility to write the core dump, instead of reading the process memory | ||||||||||
Done Inline Actions
markj: | ||||||||||
and constructing the dump by | ||||||||||
Done Inline Actions
markj: | ||||||||||
.Nm | ||||||||||
code. | ||||||||||
This is both faster and more precise, also the dump is written by the | ||||||||||
same kernel code that writes core dumps upon fatal signals. | ||||||||||
Done Inline Actions
markj: | ||||||||||
Done Inline ActionsI'm not sure what "precise" really means here. AFAIK gcore also stops the process while collecting a core, so there shouldn't be any consistency problems, and gcore includes most (all?) of the same notes as the kernel core dumper. markj: I'm not sure what "precise" really means here. AFAIK gcore also stops the process while… | ||||||||||
Done Inline ActionsBy 'precise' I mean that it match the kernel-generated dumps both now and in future, if e.g. some notes or new kinds of segments are added to the kernel dumper, which not yet copied to gcore. kib: By 'precise' I mean that it match the kernel-generated dumps both now and in future, if e.g. | ||||||||||
Done Inline ActionsYou already say that in the same sentence though, so I would drop "precise". Without this explanation the meaning of "precise" there is not obvious IMO. markj: You already say that in the same sentence though, so I would drop "precise". Without this… | ||||||||||
.El | .El | |||||||||
.Sh FILES | .Sh FILES | |||||||||
.Bl -tag -width /var/log/messages -compact | .Bl -tag -width /var/log/messages -compact | |||||||||
.It Pa core.<pid> | .It Pa core.<pid> | |||||||||
the core image | the core image | |||||||||
.El | .El | |||||||||
.Sh HISTORY | .Sh HISTORY | |||||||||
A | A | |||||||||
Show All 19 Lines |
I think convention is for non-arg flags to come first, all together? So [-fk] [-c core]?