Changeset View
Standalone View
lib/libc/sys/ptrace.2
.\" $FreeBSD$ | .\" $FreeBSD$ | |||||||||
.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ | .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ | |||||||||
.\" | .\" | |||||||||
.\" This file is in the public domain. | .\" This file is in the public domain. | |||||||||
.Dd July 15, 2019 | .Dd April 10, 2021 | |||||||||
.Dt PTRACE 2 | .Dt PTRACE 2 | |||||||||
.Os | .Os | |||||||||
.Sh NAME | .Sh NAME | |||||||||
.Nm ptrace | .Nm ptrace | |||||||||
.Nd process tracing and debugging | .Nd process tracing and debugging | |||||||||
.Sh LIBRARY | .Sh LIBRARY | |||||||||
.Lb libc | .Lb libc | |||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | |||||||||
▲ Show 20 Lines • Show All 788 Lines • ▼ Show 20 Lines | ||||||||||
.Va pve_start | .Va pve_start | |||||||||
and extends up to | and extends up to | |||||||||
.Va pve_end | .Va pve_end | |||||||||
(inclusive). | (inclusive). | |||||||||
.Pp | .Pp | |||||||||
The | The | |||||||||
.Fa data | .Fa data | |||||||||
argument is ignored. | argument is ignored. | |||||||||
.It Dv PT_COREDUMP | ||||||||||
This request creates a coredump for the stopped program. | ||||||||||
The | ||||||||||
emaste: The
.Fa addr
argument... | ||||||||||
.Fa addr | ||||||||||
argument specifies a pointer to a | ||||||||||
.Vt "struct ptrace_coredump" , | ||||||||||
which is defined as follows: | ||||||||||
.Bd -literal | ||||||||||
struct ptrace_coredump { | ||||||||||
int pc_fd; | ||||||||||
uint32_t pc_flags; | ||||||||||
off_t pc_limit; | ||||||||||
}; | ||||||||||
.Ed | ||||||||||
The fields of the structure are: | ||||||||||
.Bl -tag -width pc_flags | ||||||||||
.It Dv pc_fd | ||||||||||
Done Inline ActionsShould we indicate what type(s) of file descriptors are permissible? emaste: Should we indicate what type(s) of file descriptors are permissible? | ||||||||||
File descriptor to write the dump to. | ||||||||||
It must refer to a regular file, opened for write. | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
.It Dv pc_flags | ||||||||||
Flags. | ||||||||||
The following flags are defined: | ||||||||||
.Bl -tag -width PC_COMPRESS | ||||||||||
.It Dv PC_COMPRESS | ||||||||||
Request compression of the dump. | ||||||||||
Done Inline ActionsCan we clarify non-dumpable? emaste: Can we clarify non-dumpable?
Do we need a comment in mmap(2) alongside `MAP_NOCORE`? I assume… | ||||||||||
.It Dv PC_ALL | ||||||||||
Include non-dumpable entries into the dump. | ||||||||||
The dumper ignores | ||||||||||
.Dv MAP_NOCORE | ||||||||||
flag of the process map entry, but device mappings are not dumped even with | ||||||||||
.Dv PC_ALL | ||||||||||
set. | ||||||||||
.El | ||||||||||
.It Dv pc_limit | ||||||||||
Maximum size of the coredump. | ||||||||||
Specify zero for no limit. | ||||||||||
.El | ||||||||||
Done Inline ActionsMaybe "must already be stopped"? emaste: Maybe "must already be stopped"? | ||||||||||
.Pp | ||||||||||
The size of | ||||||||||
.Vt "struct ptrace_coredump" | ||||||||||
must be passed in | ||||||||||
.Fa data . | ||||||||||
.Pp | ||||||||||
The process must be already stopped for dumping core. | ||||||||||
Done Inline Actions
markj: | ||||||||||
A single thread in the target process is temporarily unsuspended | ||||||||||
in kernel to write the dump. | ||||||||||
Since the thread is stopped after the write, the process must be | ||||||||||
Done Inline Actions
markj: | ||||||||||
waited for using | ||||||||||
.Xr waitpid 2 | ||||||||||
after the request to consume the stop event. | ||||||||||
markjUnsubmitted Done Inline ActionsSo in some error cases this is not true. How does userspace know whether it needs to wait? markj: So in some error cases this is not true. How does userspace know whether it needs to wait? | ||||||||||
kibAuthorUnsubmitted Done Inline ActionsI propose to not care about the difference, see updated man page and my other reply. kib: I propose to not care about the difference, see updated man page and my other reply. | ||||||||||
.El | .El | |||||||||
Done Inline Actions
markj: | ||||||||||
.Sh ARM MACHINE-SPECIFIC REQUESTS | .Sh ARM MACHINE-SPECIFIC REQUESTS | |||||||||
.Bl -tag -width "Dv PT_SETVFPREGS" | .Bl -tag -width "Dv PT_SETVFPREGS" | |||||||||
.It Dv PT_GETVFPREGS | .It Dv PT_GETVFPREGS | |||||||||
Return the thread's | Return the thread's | |||||||||
Done Inline Actions
markj: | ||||||||||
.Dv VFP | .Dv VFP | |||||||||
machine state in the buffer pointed to by | machine state in the buffer pointed to by | |||||||||
.Fa addr . | .Fa addr . | |||||||||
.Pp | .Pp | |||||||||
The | The | |||||||||
.Fa data | .Fa data | |||||||||
argument is ignored. | argument is ignored. | |||||||||
Done Inline ActionsI believe there is no race here if a thread was unsuspended: after ptrace(PT_COREDUMP) returns, the use of the proc lock in ptracestop() ensures that the new stop event is immediately visible to a waitpid(WNOHANG) caller. Is that correct? I am just concerned about waitpid(WNOHANG) returning a false negative, i.e., there is a new stop event to consume but waitpid(WNOHANG) did not consume it because the re-suspension happens asynchronously. markj: I believe there is no race here if a thread was unsuspended: after ptrace(PT_COREDUMP) returns… | ||||||||||
Done Inline ActionsThe waitpid(WNOHANG) should be executed atfer ptrace(PT_COREDUMP) returned. The unsuspended thread suspends itself, which generates the event by thread_suspend_switch()->thread_stopped()->childproc_stopped() before wakeup. So you are right that there is no race, but the main reason is that the event generation is in fact synchronous. kib: The waitpid(WNOHANG) should be executed atfer ptrace(PT_COREDUMP) returned. The unsuspended… | ||||||||||
Done Inline ActionsDoesn't the wakeup happen in ptrace_coredump(), before the thread_suspend_switch() call? markj: Doesn't the wakeup happen in ptrace_coredump(), before the thread_suspend_switch() call? | ||||||||||
Done Inline ActionsHm, yes. I think I will not change anything, because indeed the process lock is held. But the sleep/wakeup there can be changed to p->p_pptr wchan, and then wakeup in ptrace_coredump() is not needed. kib: Hm, yes. I think I will not change anything, because indeed the process lock is held. But the… | ||||||||||
.It Dv PT_SETVFPREGS | .It Dv PT_SETVFPREGS | |||||||||
Set the thread's | Set the thread's | |||||||||
.Dv VFP | .Dv VFP | |||||||||
machine state from the buffer pointed to by | machine state from the buffer pointed to by | |||||||||
.Fa addr . | .Fa addr . | |||||||||
.Pp | .Pp | |||||||||
The | The | |||||||||
.Fa data | .Fa data | |||||||||
▲ Show 20 Lines • Show All 342 Lines • Show Last 20 Lines |
The
.Fa addr
argument...