<?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>

<indexterm>
<primary>script examples</primary>
<secondary>monitoring reads and writes to a file</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>monitoring reads and writes to a file</secondary>
</indexterm>

<indexterm>
<primary>monitoring reads and writes to a file</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<indexterm>
<primary>file reads/writes, monitoring</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<indexterm>
	<primary>reads/writes to a file, monitoring</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<indexterm>
	<primary>writes/reads to a file, monitoring</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<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><xi:include parse="text" href="../testsuite/systemtap.examples/io/inodewatch.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</para>
</formalpara>

<remark>need to add references to sources/man pages that explain how "dev_nr = $file->f_dentry->d_inode->i_sb->s_dev" and "($1 &lt;&lt; 20 | $2)".</remark>


<para><xref linkend="inodewatch"/> takes the following information about the
file as arguments on the command line:</para>
<indexterm>
	<primary>script examples</primary>
	<secondary>file device number (integer format)</secondary>
</indexterm>

<indexterm>
	<primary>examples of SystemTap scripts</primary>
	<secondary>file device number (integer format)</secondary>
</indexterm>

<indexterm>
	<primary>file device number (integer format)</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<indexterm>
	<primary>device number of a file (integer format)</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<itemizedlist>
	<listitem><para>The file's major device number.</para></listitem>

	<listitem><para>The file's minor device number.</para></listitem>

	<listitem><para>The file's <command>inode</command> number.</para></listitem>
</itemizedlist>
<indexterm>
	<primary>script examples</primary>
	<secondary>stat -c, determining file device number (integer format)</secondary>
</indexterm>

<indexterm>
	<primary>examples of SystemTap scripts</primary>
	<secondary>stat -c, determining file device number (integer format)</secondary>
</indexterm>

<indexterm>
	<primary>stat -c, determining file device number (integer format)</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<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: 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>
<indexterm>
	<primary>script examples</primary>
	<secondary>inode number</secondary>
</indexterm>

<indexterm>
	<primary>examples of SystemTap scripts</primary>
	<secondary>inode number</secondary>
</indexterm>

<indexterm>
	<primary>inode number</primary>
	<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<para><computeroutput>805</computeroutput> is the base-16 (hexadecimal) device number. The lower two digits are the minor device number and the upper digits are the major number. <computeroutput>1078319</computeroutput> is the <command>inode</command> number. To start monitoring <filename>/etc/crontab</filename>, run <command>stap inodewatch.stp 0x8 0x05 1078319</command> (The <command>0x</command> prefixes indicate base-16 values.</para>

<para>The output of this command contains the name and ID of any process performing a read/write, the function it is performing (that is, <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 0x8 0x05 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>

<!--
      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)
}

      -->

	</section>

