changeset 699:8205c2fcde2f

Fixed long lines, apostrophes used, etc.
author Ruslan Ermilov <ru@nginx.com>
date Wed, 03 Oct 2012 10:20:50 +0000
parents 5182e655d055
children 825aa0a98b24
files xml/en/docs/nginx_dtrace_pid_provider.xml
diffstat 1 files changed, 46 insertions(+), 36 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/nginx_dtrace_pid_provider.xml
+++ b/xml/en/docs/nginx_dtrace_pid_provider.xml
@@ -6,7 +6,6 @@
 
 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
 
-
 <article name="Debugging nginx with DTrace pid provider"
 	link="/en/docs/nginx_dtrace_pid_provider.html"
 	lang="en"
@@ -16,18 +15,20 @@
 <section>
 
 <para>
-This article assumes the reader has a general knowledge of nginx internals and 
+This article assumes the reader has a general knowledge of nginx internals and
 <link id="see_also">DTrace</link>.
 </para>
 
 <para>
-Although nginx build with <link doc="debugging_log.xml">--with-debug</link> option
-already provides a lot of information about request processing, it is sometimes desirable
-to trace particular parts of code path more thoroughly and at the same time
-omit the rest of debug output. DTrace pid provider (available on Solaris, OS X) is a useful
-tool to explore userland programs internals, since it doesn't require any code changes and
-it can help with the task. E.g. a simple DTrace script to trace and print nginx 
-functions calls may look like:
+Although nginx build with <link doc="debugging_log.xml">--with-debug</link>
+option already provides a lot of information about request processing,
+it is sometimes desirable to trace particular parts of code path more
+thoroughly and at the same time omit the rest of debug output.
+DTrace pid provider (available on Solaris, OS X) is a useful tool to
+explore userland programs internals, since it doesn’t require any code
+changes and it can help with the task.
+E.g. a simple DTrace script to trace and print nginx functions calls
+may look like:
 
 <programlisting>
 #pragma D option flowindent
@@ -43,10 +44,11 @@ pid$target:nginx::return {
 
 <para>
 DTrace capabilities for function calls tracing provide only a limited amount
-of useful information, though. Real-time inspection of function arguments
-is typically more interesting, but also a bit more complicated. Examples below
-are intended to help the reader become more familiar with DTrace and the
-process of analyzing nginx behavior using DTrace.
+of useful information, though.
+Real-time inspection of function arguments is typically more interesting,
+but also a bit more complicated.
+Examples below are intended to help the reader become more familiar with
+DTrace and the process of analyzing nginx behavior using DTrace.
 </para>
 
 <para>
@@ -64,7 +66,7 @@ pid$target::*ngx_http_process_request:en
     this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t));
     this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data,
                                          this->request->request_line.len));
-    printf("request line = %s\n", this->request_line); 
+    printf("request line = %s\n", this->request_line);
     printf("request start sec = %d\n", this->request->start_sec);
 }
 
@@ -72,14 +74,16 @@ pid$target::*ngx_http_process_request:en
 </para>
 
 <para>
-It should be noted that in the example above DTrace requires some knowledge about
-<literal>ngx_http_process_request</literal> structure.
+It should be noted that in the example above DTrace requires some knowledge
+about <literal>ngx_http_process_request</literal> structure.
 Unfortunately while it is possible to use a specific <literal>#include</literal>
 directive in the DTrace script and then pass it to a C preprocessor
-(with -C flag), that doesn't really work. Due to a lot of cross dependencies almost
-all nginx header files have to be included. In turn, based on configure script
-settings, nginx headers will include PCRE, OpenSSL and a variety of system header
-files. While in theory all those header files related to a specific nginx build
+(with -C flag), that doesn’t really work.
+Due to a lot of cross dependencies almost all nginx header files
+have to be included.
+In turn, based on configure script settings, nginx headers will include PCRE,
+OpenSSL and a variety of system header files.
+While in theory all those header files related to a specific nginx build
 might be included in DTrace script preprocessing and compilation, in reality
 DTrace script most probably will fail to compile because of unknown syntax in
 some header files.
@@ -87,31 +91,36 @@ some header files.
 
 <para>
 The problem above can be solved by including only the relevant and
-necessary structures and types definitions in the DTrace script. DTrace has to know
-sizes of structures, types, and fields offsets. Thus dependencies can be further
-reduced by manually optimizing structure definitions for use with DTrace.
+necessary structures and types definitions in the DTrace script.
+DTrace has to know sizes of structures, types, and fields offsets.
+Thus dependencies can be further reduced by manually optimizing
+structure definitions for use with DTrace.
 </para>
 
 <para>
-Let's use DTrace script example above and see what structure definitions it needs
-to work properly.
+Let’s use DTrace script example above and see what structure definitions
+it needs to work properly.
 </para>
 
 <para>
-First of all <literal>objs/ngx_auto_config.h</literal> file generated by configure
-should be included, because it defines a number of constants affecting various
-<literal>#ifdef's</literal>. After that there's some basic types and definitions
+First of all <literal>objs/ngx_auto_config.h</literal> file generated by
+configure should be included, because it defines a number of constants
+affecting various <literal>#ifdef’s</literal>.
+After that there’s some basic types and definitions
 like <literal>ngx_str_t</literal>, <literal>ngx_table_elt_t</literal>,
-<literal>ngx_uint_t</literal> etc. should be put at the beginning of DTrace script.
-These definitions are compact, commonly used and unlikely to be frequently changed.
+<literal>ngx_uint_t</literal> etc. should be put at the beginning of
+DTrace script.
+These definitions are compact, commonly used and unlikely to be
+frequently changed.
 </para>
 
 <para>
-Then there's the <literal>ngx_http_process_request_t</literal> structure which
-contains a lot of pointers to other structures. Because these pointers are
-really irrelevant to this script, and because they have the same size,
-it is possible to just replace them with void pointers. Instead of changing
-definitions, it is better to add appropriate typedefs, though:
+Then there’s the <literal>ngx_http_process_request_t</literal> structure which
+contains a lot of pointers to other structures.
+Because these pointers are really irrelevant to this script, and because they
+have the same size, it is possible to just replace them with void pointers.
+Instead of changing definitions, it is better to add appropriate typedefs,
+though:
 
 <programlisting>
 typedef ngx_http_upstream_t     void;
@@ -125,7 +134,7 @@ declarations and constants definitions.
 </para>
 
 <para>
-Final DTrace script can be downloaded 
+Final DTrace script can be downloaded
 <link url="http://nginx.org/download/trace_process_request.d">here</link>.
 </para>
 
@@ -151,6 +160,7 @@ nginx functions calls.
 
 </section>
 
+
 <section id="see_also"
          name="See also">