libstatgrab/docs/sg_get_mem_stats.xml

<?xml version="1.0"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sg_get_mem_stats">

  <refentryinfo>
    <date>$Date: 2004/05/02 09:35:15 $</date>
    <releaseinfo>$Id: sg_get_mem_stats.xml,v 1.4 2004/05/02 09:35:15 tdb Exp $</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sg_get_mem_stats</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>sg_get_mem_stats</refname>
    <refname>sg_get_swap_stats</refname>
    <refpurpose>get VM statistics</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      Memory statistics are accessed through the
      <function>sg_get_mem_stats</function> function. It returns a
      pointer to a static <structname>sg_mem_stats</structname>.
    </para>
    <para>
      The <function>sg_get_swap_stats</function> returns returns swap
      statistics. It returns a pointer to a static
      <structname>sg_swap_stats</structname>.
    </para>
    <para>
      On the FreeBSD operating system elevated privileges are required
      to access the swap statistics. Making the program setgid kmem
      should be sufficient. Programs running as root will not have this
      problem.
    </para>
  </refsect1>

  <refsect1>
    <title>Return Values</title>

    <para>
      The VM system calls can return a pointer to either a
      <structname>sg_mem_stats</structname> or a
      <structname>sg_swap_stats</structname>.
    </para>

    <programlisting>
typedef struct{
        long long total;
        long long free;
        long long used;
        long long cache;
}sg_mem_stats;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term>
          <structfield>total</structfield>
        </term>
        <listitem>
          <para>
            The total amount of memory in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>free</structfield>
        </term>
        <listitem>
          <para>
            The total free memory in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>used</structfield>
        </term>
        <listitem>
          <para>
            The total used memory in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>cache</structfield>
        </term>
        <listitem>
          <para>
            The amount of cache used in bytes.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <programlisting>
typedef struct{
        long long total;
        long long used;
        long long free;
}sg_swap_stats;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term>
          <structfield>total</structfield>
        </term>
        <listitem>
          <para>
            The total swap space in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>used</structfield>
        </term>
        <listitem>
          <para>
            The used swap in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>free</structfield>
        </term>
        <listitem>
          <para>
            The free swap in bytes.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Todo</title>
    <para>
      Add a function to hold open the file descriptor to the kernel
      memory structures. Doing this would allow the elevated privileges
      to be dropped early on.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>statgrab</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
      </member>
    </simplelist>
  </refsect1>

  <refsect1>
    <title>Website</title>

    <simplelist type="vert">
      <member>
        <ulink url="http://www.i-scream.org/libstatgrab/">
          http://www.i-scream.org/libstatgrab/
        </ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.5
Committed:	Sun May 2 17:21:35 2004 UTC (20 years ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_11_1, LIBSTATGRAB_0_11, LIBSTATGRAB_0_10_3, LIBSTATGRAB_0_10_2, LIBSTATGRAB_0_10_1, LIBSTATGRAB_0_10
Changes since 1.4:	+34 -34 lines
Log Message:	First pass as updating contents of documentation.
#	User	Rev	Content
1	tdb	1.1	<?xml version="1.0"?>
2
3			<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4			"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
6	tdb	1.5	<refentry id="sg_get_mem_stats">
7	tdb	1.1
8			<refentryinfo>
9	tdb	1.5	<date>$Date: 2004/05/02 09:35:15 $</date>
10			<releaseinfo>$Id: sg_get_mem_stats.xml,v 1.4 2004/05/02 09:35:15 tdb Exp $</releaseinfo>
11	tdb	1.1	</refentryinfo>
12	tdb	1.5
13	tdb	1.1	<refmeta>
14	tdb	1.5	<refentrytitle>sg_get_mem_stats</refentrytitle>
15	tdb	1.1	<manvolnum>3</manvolnum>
16			<refmiscinfo>i-scream</refmiscinfo>
17			</refmeta>
18	tdb	1.5
19	tdb	1.1	<refnamediv>
20	tdb	1.5	<refname>sg_get_mem_stats</refname>
21			<refname>sg_get_swap_stats</refname>
22	tdb	1.1	<refpurpose>get VM statistics</refpurpose>
23			</refnamediv>
24	tdb	1.5
25	tdb	1.1	<refsynopsisdiv>
26			<funcsynopsis>
27			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
28			<funcprototype>
29	tdb	1.5	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
30	tdb	1.1	<void/>
31			</funcprototype>
32			<funcprototype>
33	tdb	1.5	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
34	tdb	1.1	<void/>
35			</funcprototype>
36			</funcsynopsis>
37			</refsynopsisdiv>
38	tdb	1.5
39	tdb	1.1	<refsect1>
40			<title>Description</title>
41			<para>
42			Memory statistics are accessed through the
43	tdb	1.5	<function>sg_get_mem_stats</function> function. It returns a
44			pointer to a static <structname>sg_mem_stats</structname>.
45	tdb	1.1	</para>
46			<para>
47	tdb	1.5	The <function>sg_get_swap_stats</function> returns returns swap
48	tdb	1.1	statistics. It returns a pointer to a static
49	tdb	1.5	<structname>sg_swap_stats</structname>.
50	tdb	1.1	</para>
51			<para>
52			On the FreeBSD operating system elevated privileges are required
53			to access the swap statistics. Making the program setgid kmem
54			should be sufficient. Programs running as root will not have this
55			problem.
56			</para>
57			</refsect1>
58	tdb	1.5
59	tdb	1.1	<refsect1>
60			<title>Return Values</title>
61
62			<para>
63			The VM system calls can return a pointer to either a
64	tdb	1.5	<structname>sg_mem_stats</structname> or a
65			<structname>sg_swap_stats</structname>.
66	tdb	1.1	</para>
67
68			<programlisting>
69			typedef struct{
70			long long total;
71			long long free;
72			long long used;
73			long long cache;
74	tdb	1.5	}sg_mem_stats;
75	tdb	1.1	</programlisting>
76
77			<variablelist>
78			<varlistentry>
79			<term>
80			<structfield>total</structfield>
81			</term>
82			<listitem>
83			<para>
84			The total amount of memory in bytes.
85			</para>
86			</listitem>
87			</varlistentry>
88			<varlistentry>
89			<term>
90			<structfield>free</structfield>
91			</term>
92			<listitem>
93			<para>
94			The total free memory in bytes.
95			</para>
96			</listitem>
97			</varlistentry>
98			<varlistentry>
99			<term>
100			<structfield>used</structfield>
101			</term>
102			<listitem>
103			<para>
104			The total used memory in bytes.
105			</para>
106			</listitem>
107			</varlistentry>
108			<varlistentry>
109			<term>
110			<structfield>cache</structfield>
111			</term>
112			<listitem>
113			<para>
114			The amount of cache used in bytes.
115			</para>
116			</listitem>
117			</varlistentry>
118			</variablelist>
119
120			<programlisting>
121			typedef struct{
122			long long total;
123			long long used;
124			long long free;
125	tdb	1.5	}sg_swap_stats;
126	tdb	1.1	</programlisting>
127
128			<variablelist>
129			<varlistentry>
130			<term>
131			<structfield>total</structfield>
132	tdb	1.5	</term>
133	tdb	1.1	<listitem>
134	tdb	1.5	<para>
135	tdb	1.1	The total swap space in bytes.
136			</para>
137			</listitem>
138			</varlistentry>
139			<varlistentry>
140	tdb	1.5	<term>
141	tdb	1.1	<structfield>used</structfield>
142	tdb	1.5	</term>
143	tdb	1.1	<listitem>
144	tdb	1.5	<para>
145	tdb	1.1	The used swap in bytes.
146			</para>
147			</listitem>
148			</varlistentry>
149			<varlistentry>
150	tdb	1.5	<term>
151	tdb	1.1	<structfield>free</structfield>
152	tdb	1.5	</term>
153			<listitem>
154			<para>
155	tdb	1.1	The free swap in bytes.
156	tdb	1.5	</para>
157			</listitem>
158	tdb	1.1	</varlistentry>
159			</variablelist>
160			</refsect1>
161
162			<refsect1>
163			<title>Todo</title>
164			<para>
165			Add a function to hold open the file descriptor to the kernel
166			memory structures. Doing this would allow the elevated privileges
167			to be dropped early on.
168			</para>
169			</refsect1>
170
171			<refsect1>
172			<title>See Also</title>
173	tdb	1.2
174			<simplelist type="inline">
175			<member>
176			<citerefentry>
177			<refentrytitle>statgrab</refentrytitle>
178			<manvolnum>3</manvolnum>
179			</citerefentry>
180			</member>
181			</simplelist>
182	tdb	1.1	</refsect1>
183	tdb	1.5
184	tdb	1.1	<refsect1>
185			<title>Website</title>
186	tdb	1.5
187	tdb	1.1	<simplelist type="vert">
188			<member>
189	tdb	1.3	<ulink url="http://www.i-scream.org/libstatgrab/">
190			http://www.i-scream.org/libstatgrab/
191			</ulink>
192	tdb	1.1	</member>
193			</simplelist>
194			</refsect1>
195
196			</refentry>