home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V6 / usr / man / man2 / ptrace.2 < prev    next >
Encoding:
Text File  |  1975-06-26  |  4.1 KB  |  169 lines
  1. .th PTRACE II 1/25/75
  2. .sh NAME
  3. ptrace  \*-  process trace
  4. .sh SYNOPSIS
  5. .nf
  6. (ptrace = 26.; not in assembler)
  7. (data in r0)
  8. .ft B
  9. sys    ptrace; pid; addr; request
  10. .ft R
  11. .br
  12. (value in r0)
  13. .ft B
  14. .s3
  15. ptrace(request, pid, addr, data);
  16. .ft R
  17. .fi
  18. .sh DESCRIPTION
  19. .it Ptrace
  20. provides a means by which a parent process
  21. may control the execution of a child process,
  22. and examine and change its core image.
  23. Its primary use is for the implementation of breakpoint debugging,
  24. but it should be adaptable for simulation of non-UNIX environments.
  25. There are four arguments whose interpretation
  26. depends on a
  27. .it request
  28. argument.
  29. Generally,
  30. .it pid
  31. is the process ID of the traced process,
  32. which must be a child (no more distant descendant)
  33. of the tracing process.
  34. A process being traced
  35. behaves normally until it encounters some signal whether internally generated
  36. like ``illegal instruction'' or externally generated like ``interrupt.''
  37. See signal (II) for the list.
  38. Then the traced process enters a stopped state
  39. and its parent is notified via
  40. .it wait
  41. (II).
  42. When the child is in the stopped state,
  43. its core image can be examined and modified
  44. using
  45. .it ptrace.
  46. If desired, another
  47. .it ptrace
  48. request can then cause the child either to terminate
  49. or to continue, possibly ignoring the signal.
  50. .s3
  51. The value of the
  52. .it request
  53. argument determines the precise
  54. action of the call:
  55. .s3
  56. .lp +4 4
  57. 0    This request is the only one used by the child process;
  58. it declares that the process is to be traced by its parent.
  59. All the other arguments are ignored.
  60. Peculiar results will ensue
  61. if the parent does not expect to trace the child.
  62. .s3
  63. .lp +4 4
  64. 1,2    The
  65. word in the child process's address space
  66. at
  67. .it addr
  68. is returned (in r0).
  69. Request 1 indicates the data space (normally used);
  70. 2 indicates the instruction space (when I and D space are separated).
  71. .it addr
  72. must be even.
  73. The child must be stopped.
  74. The input
  75. .it data
  76. is ignored.
  77. .s3
  78. .lp +4 4
  79. 3    The word
  80. of the system's per-process data area corresponding to
  81. .it addr
  82. is returned.
  83. .it Addr
  84. must be even and less than 512.
  85. This space contains the registers and other information about
  86. the process;
  87. its layout corresponds to the
  88. .it user
  89. structure in the system.
  90. .s3
  91. .lp +4 4
  92. 4,5    The
  93. given
  94. .it data
  95. is written at the word in the process's address space corresponding to
  96. .it addr,
  97. which must be even.
  98. No useful value is returned.
  99. Request 4 specifies data space (normally used), 5 specifies
  100. instruction space.
  101. Attempts to write in pure procedure result in termination of the
  102. child, instead of going through or causing an error for the parent.
  103. .s3
  104. .lp +4 4
  105. 6    The process's system data is written,
  106. as it is read with request 3.
  107. Only a few locations can be written in this way:
  108. the general registers,
  109. the floating point status and registers,
  110. and certain bits of the processor status word.
  111. .s3
  112. .lp +4 4
  113. 7    The
  114. .it data
  115. argument is taken as a signal number
  116. and the child's execution continues
  117. as if it had incurred that signal.
  118. Normally the signal number will be
  119. either 0 to indicate that the signal which caused the stop
  120. should be ignored,
  121. or that value fetched out of the
  122. process's image indicating which signal caused
  123. the stop.
  124. .s3
  125. .lp +4 4
  126. 8    The traced process terminates.
  127. .s3
  128. .i0
  129. As indicated,
  130. these calls
  131. (except for request 0)
  132. can be used only when the subject process has stopped.
  133. The
  134. .it wait
  135. call is used to determine
  136. when a process stops;
  137. in such a case the ``termination'' status
  138. returned by
  139. .it wait
  140. has the value 0177 to indicate stoppage rather
  141. than genuine termination.
  142. .s3
  143. To forestall possible fraud,
  144. .it ptrace
  145. inhibits the set-user-id facility
  146. on subsequent
  147. .it exec
  148. (II)
  149.  calls.
  150. .sh "SEE ALSO"
  151. wait (II), signal (II), cdb (I)
  152. .sh DIAGNOSTICS
  153. From assembler, the c-bit (error bit) is set on errors;
  154. from C, \-1 is returned and
  155. .it errno
  156. has the error code.
  157. .sh BUGS
  158. The request 0 call should be able to specify
  159. signals which are to be treated normally and not cause a stop.
  160. In this way, for example,
  161. programs with simulated floating point (which
  162. use ``illegal instruction'' signals at a very high rate)
  163. could be efficiently debugged.
  164. .s3
  165. Also, it should be possible to stop a process on occurrence of a system
  166. call;
  167. in this way a completely controlled environment could
  168. be provided.
  169.