added new stuff

5 files changed, 150 insertions, 4 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml
new file mode 100644
index 00000000..96e58bb4
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml
@@ -0,0 +1,71 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+
+	<section id="inodewatchsect">
+		<title>Monitoring Reads and Writes to a File</title>
+		
+		
+<remark>
+WAR STORY: monitoring inode activity http://sourceware.org/systemtap/wiki/WSFileMonitor?highlight=((WarStories))
+</remark>
+		
+<remark>
+no script in examples
+</remark>	
+				
+		
+	<para>This section describes how to monitor reads from and writes to a file in real time. </para>
+	
+<formalpara id="inodewatch">
+		<title>inodewatch.stp</title>
+<para>
+<programlisting>
+probe kernel.function ("vfs_write"),
+      kernel.function ("vfs_read")
+{
+  dev_nr = $file->f_dentry->d_inode->i_sb->s_dev
+  inode_nr = $file->f_dentry->d_inode->i_ino
+
+  if (dev_nr == ($1 &lt;&lt; 20 | $2) # major/minor device
+      &amp;&amp; inode_nr == $3)
+    printf ("%s(%d) %s 0x%x/%u\n",
+      execname(), pid(), probefunc(), dev_nr, inode_nr)
+}
+</programlisting>
+</para>
+</formalpara>		
+
+<para><xref linkend="inodewatch"/> takes the following information about the file as an argument:</para>
+
+<itemizedlist>
+	<listitem><para>The file's device number, in integer format. When this is passed to the script as the first argument, be sure to replace any <computeroutput>0</computeroutput> with a space.</para></listitem>
+			
+	<listitem><para>The file's <command>inode</command> number.</para></listitem>
+</itemizedlist>
+
+<para>To get this information, use <command>stat -c '%D %i' <replaceable>filename</replaceable></command>, where <command><replaceable>filename</replaceable></command> is an absolute path.</para>
+
+<para>For instance: if you wish to monitor <filename>/etc/crontab</filename>, run <command>stat -c '%D %i' /etc/crontab</command> first. This gives the following output:</para>
+
+<screen>
+805 1078319
+</screen>
+
+<para><computeroutput>805</computeroutput> is the device number, while <computeroutput>1078319</computeroutput> is the <command>inode</command> number. To start monitoring <filename>/etc/crontab</filename>, run <command>stap inodewatch.stp 8 5 1078319</command>.</para>
+
+<para>The output of this command contains the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), the device number (in hex format), and the <command>inode</command> number. <xref linkend="inodewatchoutput"/> contains the output of <command>stap inodewatch.stp 8 5 1078319</command> (when <command>cat /etc/crontab</command> is executed while the script is running) :</para>
+
+
+<example id="inodewatchoutput">
+	<title><xref linkend="inodewatch"/> Sample Output</title>
+<screen>
+cat(16437) vfs_read 0x800005/1078319
+cat(16437) vfs_read 0x800005/1078319
+</screen>
+</example>
+
+
+	</section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml
new file mode 100644
index 00000000..300029cc
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml
@@ -0,0 +1,57 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+
+	<section id="inodewatch2sect">
+		<title>Monitoring Changes to File Attributes</title>
+		
+		
+<remark>
+	WAR STORY: monitoring more inode activity http://sourceware.org/systemtap/wiki/WSFileMonitor2?highlight=((WarStories))
+</remark>
+		
+<remark>
+no script in examples
+</remark>	
+				
+		
+	<para>This section describes how to monitor if any processes are changing the attributes of a targeted file, in real time. </para>
+	
+<formalpara id="inodewatch2">
+		<title>inodewatch2.stp</title>
+<para>
+<programlisting>
+global ATTR_MODE = 1 # ....
+
+probe kernel.function("inode_setattr") {
+  dev_nr = $inode->i_sb->s_dev
+  inode_nr = $inode->i_ino
+
+  if (dev_nr == ($1 &lt;&lt; 20 | $2) # major/minor device
+  &amp;&amp; inode_nr == $3
+  &amp;&amp; $attr->ia_valid &amp; ATTR_MODE)
+	printf ("%s(%d) %s 0x%x/%u %o %d\n",
+	execname(), pid(), probefunc(), dev_nr, inode_nr, $attr->ia_mode, uid())
+	}
+</programlisting>
+</para>
+</formalpara>		
+
+<para>Like <xref linkend="inodewatch"/> from <xref linkend="inodewatchsect"/>, <xref linkend="inodewatch2"/> takes the targeted file's device number (in integer format) and <command>inode</command> number as arguments. For more information on how to retrieve this information, refer to <xref linkend="inodewatchsect"/>.</para>   
+
+<para>The output for <xref linkend="inodewatch2"/> is similar to that of <xref linkend="inodewatch"/>, except that <xref linkend="inodewatch2"/> also contains the attribute changes to the monitored file, as well as the ID of the user responsible (<command>uid()</command>). <xref linkend="inodewatch2output"/> contains shows the output of <xref linkend="inodewatch2"/> while monitoring <filename>/home/joe/bigfile</filename> when user <computeroutput>joe</computeroutput> executes <command>chmod 777 /home/joe/bigfile</command> and <command>chmod 666 /home/joe/bigfile</command>.</para>    
+
+
+
+<example id="inodewatch2output">
+	<title><xref linkend="inodewatch2"/> Sample Output</title>
+<screen>
+chmod(17448) inode_setattr 0x800005/6011835 100777 500
+chmod(17449) inode_setattr 0x800005/6011835 100666 500
+</screen>
+</example>
+
+
+	</section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
index 4e438d89..3540a2c4 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
@@ -53,9 +53,11 @@ probe kernel.function(@2).return { trace(-1) }
 	<listitem><para>The probe function whose entry/exit you'd like to trace (<command>@2</command>).</para></listitem>
 </itemizedlist>
 
+<remark> please verify previous if correct; i'm particularly interested in finding out how to better describe "trigger function"</remark>
+
 <para><xref linkend="scriptcallgraph"/> uses <command>thread_indent()</command>; as such, its output contains the timestamp, process name, and thread ID of <command>@2</command> (i.e. the probe function you are tracing). For more information about <command>thread_indent()</command>, refer to its entry in <xref linkend="systemtapscript-handlers"/>.</para>
 
-		<para>The following example contains a snippet of the output for <command>stap para-callgraph.stp sys_read '*@fs/*.c'</command>:</para>
+		<para>The following example contains an excerpt from the output for <command>stap para-callgraph.stp sys_read '*@fs/*.c'</command>:</para>
 		
 	
 <example id="paracallgraphoutput">
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
index d0b91025..68b337f1 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
@@ -4,6 +4,19 @@
 
 	<section id="traceio2sect">
 		<title>I/O Monitoring (By Device)</title>
+		
+		<remark>
+			example from http://sourceware.org/systemtap/examples/io/traceio2.stp, but error
+		</remark>
+		
+		<remark>
+			WAR STORY: http://sourceware.org/systemtap/wiki/WSDeviceMonitor?highlight=((WarStories)), but script errored
+		</remark>	
+		
+		<remark>
+			was able to correct script through http://sourceware.org/systemtap/wiki/WSFileMonitor?highlight=((WarStories))
+		</remark>	
+		
 		<para>
 			This section describes how to monitor I/O activity on a specific device.
 		</para>
@@ -44,11 +57,11 @@ semantic error: field 'f_dentry' not found
 	inode_nr = $file->f_path->dentry->d_inode->i_ino
 </programlisting>
 
-<para><xref linkend="traceio2"/> takes 2 arguments: the <emphasis>major</emphasis> and <emphasis>minor</emphasis> numbers of the device you wish to monitor. Its output includes the name of the process name, process ID, the function being probes (i.e. <command>vfs_read</command> or <command>vfs_write</command>), and the byte address being read from or written to.</para>
+<para><xref linkend="traceio2"/> takes 2 arguments: the <emphasis>major</emphasis> and <emphasis>minor</emphasis> numbers of the device you wish to monitor. Its output includes the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), and the device number (in hex format).</para>
 
-<remark>please verify if "0x800005" is "the byte address being read from or written to"</remark>
+<remark>please verify if "0x800005" is "device number (in hex format)", and why it needs to be stated buy </remark>
 
-<para>The following example is a snippet from the output of <command>stap traceio2.stp 8 5</command>, where <command>8 5</command> is the MAJOR:MINOR device number of <filename>/dev/sda5</filename> (which we determined through <command>cat /sys/block/sda/sda5/dev</command>).</para>
+<para>The following example is an excerpt from the full output of <command>stap traceio2.stp 8 5</command>, where <computeroutput>8 5</computeroutput> is the MAJOR:MINOR device number of <filename>/dev/sda5</filename> (which we determined through <command>cat /sys/block/sda/sda5/dev</command>).</para>
 
 <example id="traceio2output">
 	<title><xref linkend="traceio2"/> Sample Output</title>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
index 3bc44461..d3d592ca 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -26,6 +26,9 @@
 	<xi:include href="Useful_Scripts-traceio2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!-- 	<xi:include href="Useful_Scripts-Kernel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 	<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
+	
 <!--	<xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Syscalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />