Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PTRACE(2)		  FreeBSD System Calls Manual		     PTRACE(2)

NAME
     ptrace -- process tracing and debugging

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <sys/ptrace.h>

     int
     ptrace(int	request, pid_t pid, caddr_t addr, int data);

DESCRIPTION
     The ptrace() system call provides tracing and debugging facilities.  It
     allows one	process	(the tracing process) to control another (the traced
     process).	The tracing process must first attach to the traced process,
     and then issue a series of	ptrace() system	calls to control the execution
     of	the process, as	well as	access process memory and register state.  For
     the duration of the tracing session, the traced process will be
     ``re-parented'', with its parent process ID (and resulting	behavior)
     changed to	the tracing process.  It is permissible	for a tracing process
     to	attach to more than one	other process at a time.  When the tracing
     process has completed its work, it	must detach the	traced process;	if a
     tracing process exits without first detaching all processes it has
     attached, those processes will be killed.

     Most of the time, the traced process runs normally, but when it receives
     a signal (see sigaction(2)), it stops.  The tracing process is expected
     to	notice this via	wait(2)	or the delivery	of a SIGCHLD signal, examine
     the state of the stopped process, and cause it to terminate or continue
     as	appropriate.  The signal may be	a normal process signal, generated as
     a result of traced	process	behavior, or use of the	kill(2)	system call;
     alternatively, it may be generated	by the tracing facility	as a result of
     attaching,	stepping by the	tracing	process, or an event in	the traced
     process.  The tracing process may choose to intercept the signal, using
     it	to observe process behavior (such as SIGTRAP), or forward the signal
     to	the process if appropriate.  The ptrace() system call is the mechanism
     by	which all this happens.

     A traced process may report additional signal stops corresponding to
     events in the traced process.  These additional signal stops are reported
     as	SIGTRAP	or SIGSTOP signals.  The tracing process can use the
     PT_LWPINFO	request	to determine which events are associated with a
     SIGTRAP or	SIGSTOP	signal.	 Note that multiple events may be associated
     with a single signal.  For	example, events	indicated by the PL_FLAG_BORN,
     PL_FLAG_FORKED, and PL_FLAG_EXEC flags are	also reported as a system call
     exit event	(PL_FLAG_SCX).	The signal stop	for a new child	process
     enabled via PTRACE_FORK will report a SIGSTOP signal.  All	other addi-
     tional signal stops use SIGTRAP.

     Each traced process has a tracing event mask.  An event in	the traced
     process only reports a signal stop	if the corresponding flag is set in
     the tracing event mask.  The current set of tracing event flags include:

     PTRACE_EXEC	Report a stop for a successful invocation of
			execve(2).  This event is indicated by the
			PL_FLAG_EXEC flag in the pl_flags member of struct
			ptrace_lwpinfo.

     PTRACE_SCE		Report a stop on each system call entry.  This event
			is indicated by	the PL_FLAG_SCE	flag in	the pl_flags
			member of struct ptrace_lwpinfo.

     PTRACE_SCX		Report a stop on each system call exit.	 This event is
			indicated by the PL_FLAG_SCX flag in the pl_flags mem-
			ber of struct ptrace_lwpinfo.

     PTRACE_SYSCALL	Report stops for both system call entry	and exit.

     PTRACE_FORK	This event flag	controls tracing for new child pro-
			cesses of a traced process.

			When this event	flag is	enabled, new child processes
			will enable tracing and	stop before executing their
			first instruction.  The	new child process will include
			the PL_FLAG_CHILD flag in the pl_flags member of
			struct ptrace_lwpinfo.	The traced process will	report
			a stop that includes the PL_FLAG_FORKED	flag.  The
			process	ID of the new child process will also be
			present	in the pl_child_pid member of struct
			ptrace_lwpinfo.	 If the	new child process was created
			via vfork(2), the traced process's stop	will also
			include	the PL_FLAG_VFORKED flag.  Note	that new child
			processes will be attached with	the default tracing
			event mask; they do not	inherit	the event mask of the
			traced process.

			When this event	flag is	not enabled, new child pro-
			cesses will execute without tracing enabled.

     PTRACE_LWP		This event flag	controls tracing of LWP	(kernel
			thread)	creation and destruction.  When	this event is
			enabled, new LWPs will stop and	report an event	with
			PL_FLAG_BORN set before	executing their	first instruc-
			tion, and exiting LWPs will stop and report an event
			with PL_FLAG_EXITED set	before completing their	termi-
			nation.

			Note that new processes	do not report an event for the
			creation of their initial thread, and exiting pro-
			cesses do not report an	event for the termination of
			the last thread.

     PTRACE_VFORK	Report a stop event when a parent process resumes
			after a	vfork(2).

			When a thread in the traced process creates a new
			child process via vfork(2), the	stop that reports
			PL_FLAG_FORKED and PL_FLAG_SCX occurs just after the
			child process is created, but before the thread	waits
			for the	child process to stop sharing process memory.
			If a debugger is not tracing the new child process, it
			must ensure that no breakpoints	are enabled in the
			shared process memory before detaching from the	new
			child process.	This means that	no breakpoints are
			enabled	in the parent process either.

			The PTRACE_VFORK flag enables a	new stop that indi-
			cates when the new child process stops sharing the
			process	memory of the parent process.  A debugger can
			reinsert breakpoints in	the parent process and resume
			it in response to this event.  This event is indicated
			by setting the PL_FLAG_VFORK_DONE flag.

     The default tracing event mask when attaching to a	process	via PT_ATTACH,
     PT_TRACE_ME, or PTRACE_FORK includes only PTRACE_EXEC events.  All	other
     event flags are disabled.

     The request argument specifies what operation is being performed; the
     meaning of	the rest of the	arguments depends on the operation, but	except
     for one special case noted	below, all ptrace() calls are made by the
     tracing process, and the pid argument specifies the process ID of the
     traced process or a corresponding thread ID.  The request argument	can
     be:

     PT_TRACE_ME	   This	request	is the only one	used by	the traced
			   process; it declares	that the process expects to be
			   traced by its parent.  All the other	arguments are
			   ignored.  (If the parent process does not expect to
			   trace the child, it will probably be	rather con-
			   fused by the	results; once the traced process
			   stops, it cannot be made to continue	except via
			   ptrace().)  When a process has used this request
			   and calls execve(2) or any of the routines built on
			   it (such as execv(3)), it will stop before execut-
			   ing the first instruction of	the new	image.	Also,
			   any setuid or setgid	bits on	the executable being
			   executed will be ignored.  If the child was created
			   by vfork(2) system call or rfork(2) call with the
			   RFMEM flag specified, the debugging events are
			   reported to the parent only after the execve(2) is
			   executed.

     PT_READ_I,	PT_READ_D  These requests read a single	int of data from the
			   traced process's address space.  Traditionally,
			   ptrace() has	allowed	for machines with distinct
			   address spaces for instruction and data, which is
			   why there are two requests: conceptually, PT_READ_I
			   reads from the instruction space and	PT_READ_D
			   reads from the data space.  In the current FreeBSD
			   implementation, these two requests are completely
			   identical.  The addr	argument specifies the address
			   (in the traced process's virtual address space) at
			   which the read is to	be done.  This address does
			   not have to meet any	alignment constraints.	The
			   value read is returned as the return	value from
			   ptrace().

     PT_WRITE_I, PT_WRITE_D
			   These requests parallel PT_READ_I and PT_READ_D,
			   except that they write rather than read.  The data
			   argument supplies the value to be written.

     PT_IO		   This	request	allows reading and writing arbitrary
			   amounts of data in the traced process's address
			   space.  The addr argument specifies a pointer to a
			   struct ptrace_io_desc, which	is defined as follows:

			   struct ptrace_io_desc {
				   int	   piod_op;	   /* I/O operation */
				   void	   *piod_offs;	   /* child offset */
				   void	   *piod_addr;	   /* parent offset */
				   size_t  piod_len;	   /* request length */
			   };

			   /*
			    * Operations in piod_op.
			    */
			   #define PIOD_READ_D	   1	   /* Read from	D space	*/
			   #define PIOD_WRITE_D	   2	   /* Write to D space */
			   #define PIOD_READ_I	   3	   /* Read from	I space	*/
			   #define PIOD_WRITE_I	   4	   /* Write to I space */

			   The data argument is	ignored.  The actual number of
			   bytes read or written is stored in piod_len upon
			   return.

     PT_CONTINUE	   The traced process continues	execution.  The	addr
			   argument is an address specifying the place where
			   execution is	to be resumed (a new value for the
			   program counter), or	(caddr_t)1 to indicate that
			   execution is	to pick	up where it left off.  The
			   data	argument provides a signal number to be	deliv-
			   ered	to the traced process as it resumes execution,
			   or 0	if no signal is	to be sent.

     PT_STEP		   The traced process is single	stepped	one instruc-
			   tion.  The addr argument should be passed
			   (caddr_t)1.	The data argument provides a signal
			   number to be	delivered to the traced	process	as it
			   resumes execution, or 0 if no signal	is to be sent.

     PT_KILL		   The traced process terminates, as if	PT_CONTINUE
			   had been used with SIGKILL given as the signal to
			   be delivered.

     PT_ATTACH		   This	request	allows a process to gain control of an
			   otherwise unrelated process and begin tracing it.
			   It does not need any	cooperation from the to-be-
			   traced process.  In this case, pid specifies	the
			   process ID of the to-be-traced process, and the
			   other two arguments are ignored.  This request
			   requires that the target process must have the same
			   real	UID as the tracing process, and	that it	must
			   not be executing a setuid or	setgid executable.
			   (If the tracing process is running as root, these
			   restrictions	do not apply.)	The tracing process
			   will	see the	newly-traced process stop and may then
			   control it as if it had been	traced all along.

     PT_DETACH		   This	request	is like	PT_CONTINUE, except that it
			   does	not allow specifying an	alternate place	to
			   continue execution, and after it succeeds, the
			   traced process is no	longer traced and continues
			   execution normally.

     PT_GETREGS		   This	request	reads the traced process's machine
			   registers into the ``struct reg'' (defined in
			   <machine/reg.h>) pointed to by addr.

     PT_SETREGS		   This	request	is the converse	of PT_GETREGS; it
			   loads the traced process's machine registers	from
			   the ``struct	reg'' (defined in <machine/reg.h>)
			   pointed to by addr.

     PT_GETFPREGS	   This	request	reads the traced process's floating-
			   point registers into	the ``struct fpreg'' (defined
			   in <machine/reg.h>) pointed to by addr.

     PT_SETFPREGS	   This	request	is the converse	of PT_GETFPREGS; it
			   loads the traced process's floating-point registers
			   from	the ``struct fpreg'' (defined in
			   <machine/reg.h>) pointed to by addr.

     PT_GETDBREGS	   This	request	reads the traced process's debug reg-
			   isters into the ``struct dbreg'' (defined in
			   <machine/reg.h>) pointed to by addr.

     PT_SETDBREGS	   This	request	is the converse	of PT_GETDBREGS; it
			   loads the traced process's debug registers from the
			   ``struct dbreg'' (defined in	<machine/reg.h>)
			   pointed to by addr.

     PT_LWPINFO		   This	request	can be used to obtain information
			   about the kernel thread, also known as light-weight
			   process, that caused	the traced process to stop.
			   The addr argument specifies a pointer to a struct
			   ptrace_lwpinfo, which is defined as follows:

			   struct ptrace_lwpinfo {
				   lwpid_t pl_lwpid;
				   int	   pl_event;
				   int	   pl_flags;
				   sigset_t pl_sigmask;
				   sigset_t pl_siglist;
				   siginfo_t pl_siginfo;
				   char	   pl_tdname[MAXCOMLEN + 1];
				   pid_t   pl_child_pid;
				   u_int   pl_syscall_code;
				   u_int   pl_syscall_narg;
			   };

			   The data argument is	to be set to the size of the
			   structure known to the caller.  This	allows the
			   structure to	grow without affecting older programs.

			   The fields in the struct ptrace_lwpinfo have	the
			   following meaning:
			   pl_lwpid
				   LWP id of the thread
			   pl_event
				   Event that caused the stop.	Currently
				   defined events are:
				   PL_EVENT_NONE       No reason given
				   PL_EVENT_SIGNAL     Thread stopped due to
						       the pending signal
			   pl_flags
				   Flags that specify additional details about
				   observed stop.  Currently defined flags
				   are:
				   PL_FLAG_SCE
					   The thread stopped due to system
					   call	entry, right after the kernel
					   is entered.	The debugger may exam-
					   ine syscall arguments that are
					   stored in memory and	registers
					   according to	the ABI	of the current
					   process, and	modify them, if
					   needed.
				   PL_FLAG_SCX
					   The thread is stopped immediately
					   before syscall is returning to the
					   usermode.  The debugger may examine
					   system call return values in	the
					   ABI-defined registers and/or	mem-
					   ory.
				   PL_FLAG_EXEC
					   When	PL_FLAG_SCX is set, this flag
					   may be additionally specified to
					   inform that the program being exe-
					   cuted by debuggee process has been
					   changed by successful execution of
					   a system call from the execve(2)
					   family.
				   PL_FLAG_SI
					   Indicates that pl_siginfo member of
					   struct ptrace_lwpinfo contains
					   valid information.
				   PL_FLAG_FORKED
					   Indicates that the process is
					   returning from a call to fork(2)
					   that	created	a new child process.
					   The process identifier of the new
					   process is available	in the
					   pl_child_pid	member of struct
					   ptrace_lwpinfo.
				   PL_FLAG_CHILD
					   The flag is set for first event
					   reported from a new child which is
					   automatically attached when
					   PTRACE_FORK is enabled.
				   PL_FLAG_BORN
					   This	flag is	set for	the first
					   event reported from a new LWP when
					   PTRACE_LWP is enabled.  It is
					   reported along with PL_FLAG_SCX.
				   PL_FLAG_EXITED
					   This	flag is	set for	the last event
					   reported by an exiting LWP when
					   PTRACE_LWP is enabled.  Note	that
					   this	event is not reported when the
					   last	LWP in a process exits.	 The
					   termination of the last thread is
					   reported via	a normal process exit
					   event.
				   PL_FLAG_VFORKED
					   Indicates that the thread is
					   returning from a call to vfork(2)
					   that	created	a new child process.
					   This	flag is	set in addition	to
					   PL_FLAG_FORKED.
				   PL_FLAG_VFORK_DONE
					   Indicates that the thread has
					   resumed after a child process cre-
					   ated	via vfork(2) has stopped shar-
					   ing its address space with the
					   traced process.
			   pl_sigmask
				   The current signal mask of the LWP
			   pl_siglist
				   The current pending set of signals for the
				   LWP.	 Note that signals that	are delivered
				   to the process would	not appear on an LWP
				   siglist until the thread is selected	for
				   delivery.
			   pl_siginfo
				   The siginfo that accompanies	the signal
				   pending.  Only valid	for PL_EVENT_SIGNAL
				   stop	when PL_FLAG_SI	is set in pl_flags.
			   pl_tdname
				   The name of the thread.
			   pl_child_pid
				   The process identifier of the new child
				   process.  Only valid	for a PL_EVENT_SIGNAL
				   stop	when PL_FLAG_FORKED is set in
				   pl_flags.
			   pl_syscall_code
				   The ABI-specific identifier of the current
				   system call.	 Note that for indirect	system
				   calls this field reports the	indirected
				   system call.	 Only valid when PL_FLAG_SCE
				   or PL_FLAG_SCX is set in pl_flags.
			   pl_syscall_narg
				   The number of arguments passed to the cur-
				   rent	system call not	counting the system
				   call	identifier.  Note that for indirect
				   system calls	this field reports the argu-
				   ments passed	to the indirected system call.
				   Only	valid when PL_FLAG_SCE or PL_FLAG_SCX
				   is set in pl_flags.

     PT_GETNUMLWPS	   This	request	returns	the number of kernel threads
			   associated with the traced process.

     PT_GETLWPLIST	   This	request	can be used to get the current thread
			   list.  A pointer to an array	of type	lwpid_t	should
			   be passed in	addr, with the array size specified by
			   data.  The return value from	ptrace() is the	count
			   of array entries filled in.

     PT_SETSTEP		   This	request	will turn on single stepping of	the
			   specified process.

     PT_CLEARSTEP	   This	request	will turn off single stepping of the
			   specified process.

     PT_SUSPEND		   This	request	will suspend the specified thread.

     PT_RESUME		   This	request	will resume the	specified thread.

     PT_TO_SCE		   This	request	will set the PTRACE_SCE	event flag to
			   trace all future system call	entries	and continue
			   the process.	 The addr and data arguments are used
			   the same as for PT_CONTINUE.

     PT_TO_SCX		   This	request	will set the PTRACE_SCX	event flag to
			   trace all future system call	exits and continue the
			   process.  The addr and data arguments are used the
			   same	as for PT_CONTINUE.

     PT_SYSCALL		   This	request	will set the PTRACE_SYSCALL event flag
			   to trace all	future system call entries and exits
			   and continue	the process.  The addr and data	argu-
			   ments are used the same as for PT_CONTINUE.

     PT_FOLLOW_FORK	   This	request	controls tracing for new child pro-
			   cesses of a traced process.	If data	is non-zero,
			   PTRACE_FORK is set in the traced process's event
			   tracing mask.  If data is zero, PTRACE_FORK is
			   cleared from	the traced process's event tracing
			   mask.

     PT_LWP_EVENTS	   This	request	controls tracing of LWP	creation and
			   destruction.	 If data is non-zero, PTRACE_LWP is
			   set in the traced process's event tracing mask.  If
			   data	is zero, PTRACE_LWP is cleared from the	traced
			   process's event tracing mask.

     PT_GET_EVENT_MASK	   This	request	reads the traced process's event trac-
			   ing mask into the integer pointed to	by addr.  The
			   size	of the integer must be passed in data.

     PT_SET_EVENT_MASK	   This	request	sets the traced	process's event	trac-
			   ing mask from the integer pointed to	by addr.  The
			   size	of the integer must be passed in data.

     PT_VM_TIMESTAMP	   This	request	returns	the generation number or time-
			   stamp of the	memory map of the traced process as
			   the return value from 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.

     PT_VM_ENTRY	   This	request	is used	to iterate over	the entries of
			   the VM map of the traced process.  The addr argu-
			   ment	specifies a pointer to a struct
			   ptrace_vm_entry, which is defined as	follows:

			   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;
			   };

			   The first entry is returned by setting pve_entry to
			   zero.  Subsequent entries are returned by leaving
			   pve_entry unmodified	from the value returned	by
			   previous requests.  The pve_timestamp field can be
			   used	to detect changes to the VM map	while iterat-
			   ing over the	entries.  The tracing process can then
			   take	appropriate action, such as restarting.	 By
			   setting pve_pathlen to a non-zero value on entry,
			   the pathname	of the backing object is returned in
			   the buffer pointed to by pve_path, provided the
			   entry is backed by a	vnode.	The pve_pathlen	field
			   is updated with the actual length of	the pathname
			   (including the terminating null character).	The
			   pve_offset field is the offset within the backing
			   object at which the range starts.  The range	is
			   located in the VM space at pve_start	and extends up
			   to pve_end (inclusive).

			   The data argument is	ignored.

x86 MACHINE-SPECIFIC REQUESTS
     PT_GETXMMREGS	   Copy	the XMM	FPU state into the buffer pointed to
			   by the argument addr.  The buffer has the same lay-
			   out as the 32-bit save buffer for the machine
			   instruction FXSAVE.

			   This	request	is only	valid for i386 programs, both
			   on native 32-bit systems and	on amd64 kernels.  For
			   64-bit amd64	programs, the XMM state	is reported as
			   part	of the FPU state returned by the PT_GETFPREGS
			   request.

			   The data argument is	ignored.

     PT_SETXMMREGS	   Load	the XMM	FPU state for the thread from the
			   buffer pointed to by	the argument addr.  The	buffer
			   has the same	layout as the 32-bit load buffer for
			   the machine instruction FXRSTOR.

			   As with PT_GETXMMREGS, this request is only valid
			   for i386 programs.

			   The data argument is	ignored.

     PT_GETXSTATE_INFO	   Report which	XSAVE FPU extensions are supported by
			   the CPU and allowed in userspace programs.  The
			   addr	argument must point to a variable of type
			   struct ptrace_xstate_info, which contains the
			   information on the request return.  struct
			   ptrace_xstate_info is defined as follows:

			   struct ptrace_xstate_info {
				   uint64_t	   xsave_mask;
				   uint32_t	   xsave_len;
			   };
			   The xsave_mask field	is a bitmask of	the currently
			   enabled extensions.	The meaning of the bits	is
			   defined in the Intel	and AMD	processor documenta-
			   tion.  The xsave_len	field reports the length of
			   the XSAVE area for storing the hardware state for
			   currently enabled extensions	in the format defined
			   by the x86 XSAVE machine instruction.

			   The data argument value must	be equal to the	size
			   of the struct ptrace_xstate_info.

     PT_GETXSTATE	   Return the content of the XSAVE area	for the
			   thread.  The	addr argument points to	the buffer
			   where the content is	copied,	and the	data argument
			   specifies the size of the buffer.  The kernel
			   copies out as much content as allowed by the	buffer
			   size.  The buffer layout is specified by the	layout
			   of the save area for	the XSAVE machine instruction.

     PT_SETXSTATE	   Load	the XSAVE state	for the	thread from the	buffer
			   specified by	the addr pointer.  The buffer size is
			   passed in the data argument.	 The buffer must be at
			   least as large as the struct	savefpu	(defined in
			   x86/fpu.h) to allow the complete x87	FPU and	XMM
			   state load.	It must	not be larger than the XSAVE
			   state length, as reported by	the xsave_len field
			   from	the struct ptrace_xstate_info of the
			   PT_GETXSTATE_INFO request.  Layout of the buffer is
			   identical to	the layout of the load area for	the
			   XRSTOR machine instruction.

     PT_GETFSBASE	   Return the value of the base	used when doing	seg-
			   mented memory addressing using the %fs segment reg-
			   ister.  The addr argument points to an unsigned
			   long	variable where the base	value is stored.

			   The data argument is	ignored.

     PT_GETGSBASE	   Like	the PT_GETFSBASE request, but returns the base
			   for the %gs segment register.

     PT_SETFSBASE	   Set the base	for the	%fs segment register to	the
			   value pointed to by the addr	argument.  addr	must
			   point to the	unsigned long variable containing the
			   new base.

			   The data argument is	ignored.

     PT_SETGSBASE	   Like	the PT_SETFSBASE request, but sets the base
			   for the %gs segment register.

PowerPC	MACHINE-SPECIFIC REQUESTS
     PT_GETVRREGS     Return the thread's ALTIVEC machine state	in the buffer
		      pointed to by addr.

		      The data argument	is ignored.

     PT_SETVRREGS     Set the thread's ALTIVEC machine state from the buffer
		      pointed to by addr.

		      The data argument	is ignored.

     Additionally, other machine-specific requests can exist.

RETURN VALUES
     Most requests return 0 on success and -1 on error.	 Some requests can
     cause ptrace() to return -1 as a non-error	value, among them are
     PT_READ_I and PT_READ_D, which return the value read from the process
     memory on success.	 To disambiguate, errno	can be set to 0	before the
     call and checked afterwards.

     The current ptrace() implementation always	sets errno to 0	before calling
     into the kernel, both for historic	reasons	and for	consistency with other
     operating systems.	 It is recommended to assign zero to errno explicitly
     for forward compatibility.

ERRORS
     The ptrace() system call may fail if:

     [ESRCH]
			+o   No process having the specified process ID exists.

     [EINVAL]
			+o   A process attempted	to use PT_ATTACH on itself.
			+o   The	request	argument was not one of	the legal
			    requests.
			+o   The	signal number (in data)	to PT_CONTINUE was
			    neither 0 nor a legal signal number.
			+o   PT_GETREGS,	PT_SETREGS, PT_GETFPREGS,
			    PT_SETFPREGS, PT_GETDBREGS,	or PT_SETDBREGS	was
			    attempted on a process with	no valid register set.
			    (This is normally true only	of system processes.)
			+o   PT_VM_ENTRY	was given an invalid value for
			    pve_entry.	This can also be caused	by changes to
			    the	VM map of the process.
			+o   The	size (in data) provided	to PT_LWPINFO was less
			    than or equal to zero, or larger than the
			    ptrace_lwpinfo structure known to the kernel.
			+o   The	size (in data) provided	to the x86-specific
			    PT_GETXSTATE_INFO request was not equal to the
			    size of the	struct ptrace_xstate_info.
			+o   The	size (in data) provided	to the x86-specific
			    PT_SETXSTATE request was less than the size	of the
			    x87	plus the XMM save area.
			+o   The	size (in data) provided	to the x86-specific
			    PT_SETXSTATE request was larger than returned in
			    the	xsave_len member of the	struct
			    ptrace_xstate_info from the	PT_GETXSTATE_INFO
			    request.
			+o   The	base value, provided to	the amd64-specific
			    requests PT_SETFSBASE or PT_SETGSBASE, pointed
			    outside of the valid user address space.  This
			    error will not occur in 32-bit programs.

     [EBUSY]
			+o   PT_ATTACH was attempted on a process that was
			    already being traced.
			+o   A request attempted	to manipulate a	process	that
			    was	being traced by	some process other than	the
			    one	making the request.
			+o   A request (other than PT_ATTACH) specified a
			    process that was not stopped.

     [EPERM]
			+o   A request (other than PT_ATTACH) attempted to
			    manipulate a process that was not being traced at
			    all.
			+o   An attempt was made	to use PT_ATTACH on a process
			    in violation of the	requirements listed under
			    PT_ATTACH above.

     [ENOENT]
			+o   PT_VM_ENTRY	previously returned the	last entry of
			    the	memory map.  No	more entries exist.

     [ENAMETOOLONG]
			+o   PT_VM_ENTRY	cannot return the pathname of the
			    backing object because the buffer is not big
			    enough.  pve_pathlen holds the minimum buffer size
			    required on	return.

SEE ALSO
     execve(2),	sigaction(2), wait(2), execv(3), i386_clr_watch(3),
     i386_set_watch(3)

HISTORY
     The ptrace() function appeared in Version 7 AT&T UNIX.

FreeBSD	11.1			August 29, 2016			  FreeBSD 11.1

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | x86 MACHINE-SPECIFIC REQUESTS | PowerPC MACHINE-SPECIFIC REQUESTS | RETURN VALUES | ERRORS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ptrace&sektion=2&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help