svn commit: r204814 - stable/8/lib/libc/sys

[Marcel Moolenaar]

Author: marcel
Date: Sun Mar  7 00:07:00 2010
New Revision: 204814
URL: http://svn.freebsd.org/changeset/base/204814

Log:
  MFC revs 203696, 203783:
  Add PT_VM_TIMESTAMP and PT_VM_ENTRY so that the tracing process can
  obtain the memory map of the traced process.
  
  Requested by: kib@

Modified:
  stable/8/lib/libc/sys/ptrace.2
Directory Properties:
  stable/8/lib/libc/   (props changed)
  stable/8/lib/libc/stdtime/   (props changed)

Modified: stable/8/lib/libc/sys/ptrace.2
==============================================================================
--- stable/8/lib/libc/sys/ptrace.2	Sun Mar  7 00:05:44 2010	(r204813)
+++ stable/8/lib/libc/sys/ptrace.2	Sun Mar  7 00:07:00 2010	(r204814)
@@ -2,7 +2,7 @@
 .\"	$NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
 .\"
 .\" This file is in the public domain.
-.Dd March 27, 2009
+.Dd February 11, 2010
 .Dt PTRACE 2
 .Os
 .Sh NAME
@@ -327,6 +327,68 @@ This request will trace the specified pr
 .It PT_SYSCALL
 This request will trace the specified process
 on each system call entry and exit.
+.It PT_VM_TIMESTAMP
+This request returns the generation number or timestamp of the memory map of
+the traced process as the return value from
+.Fn ptrace .
+This provides a low-cost way for the tracing process to determine if the
+VM map changed since the last time this request was made.
+.It PT_VM_ENTRY
+This request is used to iterate over the entries of the VM map of the traced
+process.
+The
+.Fa addr
+argument specifies a pointer to a 
+.Vt "struct ptrace_vm_entry" ,
+which is defined as follows:
+.Bd -literal
+struct ptrace_vm_entry {
+	int		pve_entry;
+	int		pve_timestamp;
+	u_long		pve_start;
+	u_long		pve_end;
+	u_long		pve_offset;
+	u_int		pve_prot;
+	u_int		pve_pathlen;
+	long		pve_fileid;
+	uint32_t	pve_fsid;
+	char		*pve_path;
+};
+.Ed
+.Pp
+The first entry is returned by setting
+.Va pve_entry
+to zero.
+Subsequent entries are returned by leaving
+.Va pve_entry
+unmodified from the value returned by previous requests.
+The
+.Va pve_timestamp
+field can be used to detect changes to the VM map while iterating over the
+entries.
+The tracing process can then take appropriate action, such as restarting.
+By setting
+.Va pve_pathlen
+to a non-zero value on entry, the pathname of the backing object is returned
+in the buffer pointed to by
+.Va pve_path ,
+provided the entry is backed by a vnode.
+The
+.Va pve_pathlen
+field is updated with the actual length of the pathname (including the
+terminating null character).
+The
+.Va pve_offset
+field is the offset within the backing object at which the range starts.
+The range is located in the VM space at
+.Va pve_start
+and extends up to
+.Va pve_end
+(inclusive).
+.Pp
+The
+.Fa data
+argument is ignored.
 .El
 .Pp
 Additionally, machine-specific requests can exist.
@@ -376,6 +438,11 @@ or
 .Dv PT_SETDBREGS
 was attempted on a process with no valid register set.
 (This is normally true only of system processes.)
+.It
+.Dv PT_VM_ENTRY
+was given an invalid value for
+.Fa pve_entry .
+This can also be caused by changes to the VM map of the process.
 .El
 .It Bq Er EBUSY
 .Bl -bullet -compact
@@ -405,6 +472,22 @@ on a process in violation of the require
 .Dv PT_ATTACH
 above.
 .El
+.It Bq Er ENOENT
+.Bl -bullet -compact
+.It
+.Dv PT_VM_ENTRY
+previously returned the last entry of the memory map.
+No more entries exist.
+.El
+.It Bq Er ENAMETOOLONG
+.Bl -bullet -compact
+.It
+.Dv PT_VM_ENTRY
+cannot return the pathname of the backing object because the buffer is not big
+enough.
+.Fa pve_pathlen
+holds the minimum buffer size required on return.
+.El
 .El
 .Sh SEE ALSO
 .Xr execve 2 ,