Move pitfalls discussion to its own section

dyninst · Dec 13, 2022 · fc55004 · fc55004
1 parent 0e51320
commit fc55004
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 35 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -86,6 +86,7 @@ Developed by
    overview
    building
    optimizations
+   pitfalls
 
 .. toctree::
    :caption: toolkits 

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -2,38 +2,3 @@
 ========
 Overview
 ========
-
-Common pitfalls
-===============
-
-This appendix is designed to point out some common pitfalls that users
-have reported when using the Dyninst system. Many of these are either
-due to limitations in the current implementations, or reflect design
-decisions that may not produce the expected behavior from the system.
-
-Attach followed by detach
--------------------------
-
-If a mutator attaches to a mutatee, and immediately exits, the current
-behavior is that the mutatee is left suspended. To make sure the
-application continues, call detach with the appropriate flags.
-
-Attaching to a program that has already been modified by Dyninst
-----------------------------------------------------------------
-
-If a mutator attaches to a program that has already been modified by a
-previous mutator, a warning message will be issued. We are working to
-fix this problem, but the correct semantics are still being specified.
-Currently, a message is printed to indicate that this has been
-attempted, and the attach will fail.
-
-Dyninst is event-driven
------------------------
-
-Dyninst must sometimes handle events that take place in the mutatee, for
-instance when a new shared library is loaded, or when the mutatee
-executes a fork or exec. Dyninst handles events when it checks the
-status of the mutatee, so to allow this the mutator should periodically
-call one of the functions BPatch::pollForStatusChange,
-BPatch::waitForStatusChange, BPatch_thread::isStopped, or
-BPatch_thread::isTerminated.
diff --git a/docs/pitfalls.rst b/docs/pitfalls.rst
@@ -0,0 +1,36 @@
+
+===============
+Common pitfalls
+===============
+
+These are some common pitfalls that users
+have reported when using the Dyninst system. Many of these are either
+due to limitations in the current implementations, or reflect design
+decisions that may not produce the expected behavior from the system.
+
+Attach followed by detach
+-------------------------
+
+If a mutator attaches to a mutatee, and immediately exits, the current
+behavior is that the mutatee is left suspended. To make sure the
+application continues, call detach with the appropriate flags.
+
+Attaching to a program that has already been modified by Dyninst
+----------------------------------------------------------------
+
+If a mutator attaches to a program that has already been modified by a
+previous mutator, a warning message will be issued. We are working to
+fix this problem, but the correct semantics are still being specified.
+Currently, a message is printed to indicate that this has been
+attempted, and the attach will fail.
+
+Dyninst is event-driven
+-----------------------
+
+Dyninst must sometimes handle events that take place in the mutatee, for
+instance when a new shared library is loaded, or when the mutatee
+executes a fork or exec. Dyninst handles events when it checks the
+status of the mutatee, so to allow this the mutator should periodically
+call one of the functions BPatch::pollForStatusChange,
+BPatch::waitForStatusChange, BPatch_thread::isStopped, or
+BPatch_thread::isTerminated.