New directory. Updated documentation.

1998-08-12  Martin Baulig  <martin@home-of-linux.org>

	* features: New directory.
	* gnome-hackers.sgml: Updated documentation.

7 files changed, 364 insertions, 6 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 635d9616..378ea7cf 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+1998-08-12  Martin Baulig  <martin@home-of-linux.org>
+
+	* features: New directory.
+	* gnome-hackers.sgml: Updated documentation.
+
 1998-08-11  Martin Baulig  <martin@home-of-linux.org>
 
 	* gnome-hackers.sgml: Updated documentation.
diff --git a/doc/Makefile b/doc/Makefile
index b95a67c6..00c09935 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,7 +12,9 @@ clean:
 		-V %no-make-index% libgtop.sgml > /dev/null && \
 		touch .timestamp
 
-.timestamp2:	gnome-hackers.sgml autoconf.sgml ../guile/reference.sgml
+.timestamp2:	gnome-hackers.sgml autoconf.sgml ../guile/reference.sgml \
+	features/uptime.sgml features/uptime.txt features/proclist.sgml \
+	features/procmem.sgml
 	-rm -rf gnome-hackers
 	mkdir gnome-hackers
 	-rm -f .timestamp2
diff --git a/doc/features/proclist.sgml b/doc/features/proclist.sgml
new file mode 100644
index 00000000..d071a758
--- /dev/null
+++ b/doc/features/proclist.sgml
@@ -0,0 +1,153 @@
+  <para>
+    This functions takes the following additional parameters:
+
+    <variablelist>
+      <varlistentry>
+	<term><parameter>which</parameter></term>
+	<listitem>
+
+	  <para>
+	    You can use the following constants (defined in
+	    <filename>glibtop/proclist.h</filename>) to tell
+	    <function>glibtop_get_proclist ()</function> which processes
+	    to fetch:
+
+	    <variablelist>
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_ALL</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch all processes.
+
+	      </varlistentry>
+	      
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_PID</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch process with pid <parameter>arg</parameter> or
+		    nothing if no such process exists.
+
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_PGRP</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch only processes which are in process group
+		    <parameter>arg</parameter>.
+
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_SESSION</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch only processes with session id
+		    <parameter>arg</parameter>.
+
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_TTY</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch only processes with tty id
+		    <parameter>arg</parameter>.
+		    
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_UID</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch only processes with effective user id
+		    <parameter>arg</parameter>.
+		    
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_KERN_PROC_RUID</parameter></term>
+		<listitem>
+
+		  <para>
+		    Fetch only processes with real user id
+		    <parameter>arg</parameter>.
+		    
+	      </varlistentry>
+
+	    </variablelist>
+
+	  <para>
+	    You can use one or more of the following flags (with a
+	    logical or) to hide some processes:
+
+	    <variablelist>
+	      <varlistentry>
+		<term><parameter>GLIBTOP_EXCLUDE_IDLE</parameter></term>
+		<listitem>
+
+		  <para>
+		    Don't fetch idle processes.
+
+	      </varlistentry>
+	      
+	      <varlistentry>
+		<term><parameter>GLIBTOP_EXCLUDE_SYSTEM</parameter></term>
+		<listitem>
+
+		  <para>
+		    Don't fetch system processes.
+
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><parameter>GLIBTOP_EXCLUDE_NOTTY</parameter></term>
+		<listitem>
+
+		  <para>
+		    Don't fetch processes that have no controlling tty.
+
+	      </varlistentry>
+
+	    </variablelist>
+	      
+      </varlistentry>
+
+      <varlistentry>
+	<term><parameter>arg</parameter></term>
+	<listitem>
+
+	  <para>
+	    Additional argument depending upon the
+	    <parameter>which</parameter> argument.
+
+      </varlistentry>
+    </variablelist>
+
+  <para>
+    This function returns a pointer (of type <type>unsigned *</type>) to
+    the list of process ids.
+
+  <para>
+    You have to manually &glibtop-free; this pointer once finished with it.
+  
+  <!--
+  Local Variables:
+  mode: sgml
+  sgml-omittag:t
+  sgml-shorttag:t
+  sgml-minimize-attributes:nil
+  sgml-always-quote-attributes:t
+  sgml-indent-step:2
+  sgml-indent-data: t
+  sgml-parent-document: ("../gnome-hackers.sgml" "book" "sect1" "")
+  End:
+  -->
+    
\ No newline at end of file
diff --git a/doc/features/procmem.sgml b/doc/features/procmem.sgml
new file mode 100644
index 00000000..3394afba
--- /dev/null
+++ b/doc/features/procmem.sgml
@@ -0,0 +1,103 @@
+  <para>
+    The automatically generated description above is taken from the
+    manual page of the <filename>/proc</filename> filesystem under Linux
+    and is a little bit confusing, so I make this clear here.
+    
+    <note>
+      <title>Note for people porting &libgtop; to other systems</title>
+
+      <para>
+	Well, every operating system has its own idea about the memory usage
+	of a processes, and also system utilities like <filename>ps</filename>
+	show different things on different systems.
+
+      <para>
+	Nevertheless, we should try to make &libgtop; as system independent
+	as possible, so I give you some hints here how &glibtop-get-procmem;
+	should work.
+
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      When you use &mmap; with either &MAP-SHARED; or &MAP-PRIVATE;,
+	      this should only affect the &pmem-vsize; of the process and
+	      none of its &pmem-size;, &pmem-resident;, &pmem-shared; and
+	      &pmem-rss; sizes.
+
+	  <listitem>
+	    <para>
+	      As soon as you read some of the &mmap;ed pages, they will be
+	      demand-loaded and thus count towards the &pmem-size; of the
+	      process. Also - we assume there is enough free memory - they
+	      are resident in memory until they get stolen or swapped out
+	      and thus increase the &pmem-resident; and &pmem-rss; sizes of
+	      the process.
+
+	  <listitem>
+	    <para>
+	      If the process has used &MAP-SHARED; and another process
+	      attaches the same file also &MAP-SHARED; some of the pages
+	      are shared with this process and thus increase the &pmem-shared;
+	      sizes of both processes.
+
+	  <listitem>
+	    <para>
+	      If the process has used &MAP-PRIVATE; and writes to the &mmap;ed
+	      pages, the only difference to reading from them is that they
+	      get dirty and cannot be stolen any longer but will get swapped
+	      out.
+
+	  <listitem>
+	    <para>
+	      If memory gets rare, clean pages are normally stolen which
+	      decreases the &pmem-size;, &pmem-resident;, &pmem-shared; and
+	      &pmem-rss; sizes of the process.
+
+	  <listitem>
+	    <para>
+	      When dirty pages are swapped out, this will
+	      <emphasis>not</emphasis> decrease the &pmem-size; of the
+	      process but only its &pmem-resident; and &pmem-rss; sizes
+	      (dirty pages cannot be shared).
+
+	  <listitem>
+	    <para>
+	      The &pmem-vsize; of a process can <emphasis>only</emphasis>
+	      be changed by the process itself when it requests or frees
+	      memory but <emphasis>never</emphasis> due to swapping
+	      activity of the system.
+
+	  <listitem>
+	    <para>
+	      If the &pmem-shared; size changes, this
+	      <emphasis>only</emphasis> means that the number of pages that
+	      are currently shared with other processes has changed; if this
+	      happens, this will <emphasis>never</emphasis> affect any of the
+	      other sizes of the process.
+	
+	</itemizedlist>
+
+    </note>
+
+  <para>
+    The hints above describe how it works under Linux - and we should try to
+    make &glibtop-get-procmem; show the same behavior under every other
+    system.
+
+  <para>
+    If you want to make any comments, flames, suggestions about this, please
+    feel free to do so.
+    
+    <!--
+    Local Variables:
+    mode: sgml
+    sgml-omittag:t
+    sgml-shorttag:t
+    sgml-minimize-attributes:nil
+    sgml-always-quote-attributes:t
+    sgml-indent-step:2
+    sgml-indent-data: t
+    sgml-parent-document: ("../gnome-hackers.sgml" "book" "sect1" "")
+    End:
+    -->
+  
\ No newline at end of file
diff --git a/doc/features/uptime.sgml b/doc/features/uptime.sgml
new file mode 100644
index 00000000..ea504b6a
--- /dev/null
+++ b/doc/features/uptime.sgml
@@ -0,0 +1,23 @@
+  <note>
+    
+    <para>
+      You can calculate this from the CPU usage (this one is taken
+      from the FreeBSD port):
+      
+      <programlisting>&include-uptime.txt;</programlisting>
+      
+  </note>
+  
+  <!--
+  Local Variables:
+  mode: sgml
+  sgml-omittag:t
+  sgml-shorttag:t
+  sgml-minimize-attributes:nil
+  sgml-always-quote-attributes:t
+  sgml-indent-step:2
+  sgml-indent-data: t
+  sgml-parent-document: ("../gnome-hackers.sgml" "book" "sect1" "")
+  End:
+  -->
+  
\ No newline at end of file
diff --git a/doc/features/uptime.txt b/doc/features/uptime.txt
new file mode 100644
index 00000000..be3f4489
--- /dev/null
+++ b/doc/features/uptime.txt
@@ -0,0 +1,40 @@
+#include &lt;glibtop.h&gt;
+#include &lt;glibtop/error.h&gt;
+#include &lt;glibtop/uptime.h&gt;
+
+#include &lt;glibtop/cpu.h&gt;
+
+#include &lt;glibtop_suid.h&gt;
+
+static const unsigned long _glibtop_sysdeps_uptime =
+(1 << GLIBTOP_UPTIME_UPTIME) + (1 << GLIBTOP_UPTIME_IDLETIME);
+
+static const unsigned long _required_cpu_flags =
+(1 << GLIBTOP_CPU_TOTAL) + (1 << GLIBTOP_CPU_IDLE) +
+(1 << GLIBTOP_CPU_FREQUENCY);
+
+void
+glibtop_get_uptime_p (glibtop *server, glibtop_uptime *buf)
+{
+	glibtop_cpu cpu;
+
+	glibtop_init_p (server, GLIBTOP_SYSDEPS_UPTIME, 0);
+	
+	memset (buf, 0, sizeof (glibtop_uptime));
+
+	/* We simply calculate it from the CPU usage. */
+
+	glibtop_get_cpu_p (server, &amp;cpu);
+
+	/* Make sure all required fields are present. */
+
+	if ((cpu.flags &amp; _required_cpu_flags) != _required_cpu_flags)
+		return;
+
+	/* Calculate values. */
+
+	buf->uptime = (double) cpu.total / (double) cpu.frequency;
+	buf->idletime = (double) cpu.idle / (double) cpu.frequency;
+
+	buf->flags = _glibtop_sysdeps_uptime;
+}
diff --git a/doc/gnome-hackers.sgml b/doc/gnome-hackers.sgml
index 474dde8a..9b0b03a4 100644
--- a/doc/gnome-hackers.sgml
+++ b/doc/gnome-hackers.sgml
@@ -9,10 +9,20 @@
 
 <!entity libgtop "<productname>libgtop</productname>">
 
-<!-- Some abbreviations for often used filenames. -->
+<!-- Some abbreviations for often used filenames and functions. -->
 
 <!entity gnome-libgtop-check.m4 "<filename>macros/gnome-libgtop-check.m4</filename>">
 <!entity libgtopConf.sh "<filename>libgtopConf.sh</filename>">
+<!entity glibtop-free "<function>glibtop_free ()</function>">
+<!entity glibtop-get-procmem "<function>glibtop_get_proc_mem ()</function>">
+<!entity mmap "<function>mmap ()</function>">
+<!entity MAP-SHARED "<parameter>MAP_SHARED</parameter>">
+<!entity MAP-PRIVATE "<parameter>MAP_PRIVATE</parameter>">
+<!entity pmem-vsize "<structfield>procmem.vsize</structfield>">
+<!entity pmem-size "<structfield>procmem.size</structfield>">
+<!entity pmem-resident "<structfield>procmem.resident</structfield>">
+<!entity pmem-shared "<structfield>procmem.shared</structfield>">
+<!entity pmem-rss "<structfield>procmem.rss</structfield>">
 
 <!-- This will include a sample `libgtopConf.sh'. -->
 
@@ -30,15 +40,15 @@
 <!entity include-cpu.sgml "">
 <!entity include-mem.sgml "">
 <!entity include-swap.sgml "">
-<!entity include-uptime.sgml "">
+<!entity include-uptime.sgml SYSTEM "features/uptime.sgml">
 <!entity include-loadavg.sgml "">
 <!entity include-shm-limits.sgml "">
 <!entity include-msg-limits.sgml "">
 <!entity include-sem-limits.sgml "">
-<!entity include-proclist.sgml "">
+<!entity include-proclist.sgml SYSTEM "features/proclist.sgml">
 <!entity include-proc-state.sgml "">
 <!entity include-proc-uid.sgml "">
-<!entity include-proc-mem.sgml "">
+<!entity include-proc-mem.sgml SYSTEM "features/procmem.sgml">
 <!entity include-proc-time.sgml "">
 <!entity include-proc-signal.sgml "">
 <!entity include-proc-kernel.sgml "">
@@ -46,6 +56,8 @@
 <!entity include-proc-map.sgml "">
 <!entity include-mountlist.sgml "">
 <!entity include-fsusage.sgml "">
+
+<!entity include-uptime.txt SYSTEM "features/uptime.txt">
 ]>
 <book>
   <bookinfo>
@@ -139,7 +151,27 @@
     &include-reference.sgml;
 
   </chapter>
-    
+
+  <chapter id="porting-libgtop">
+    <title>Porting &libgtop; to other systems</title>
+
+    <para>
+      Here are some comments for people porting &libgtop; to other systems.
+
+    <sect1>
+      <title>&glibtop-get-procmem; - Process Memory information</title>
+
+      <para>
+	This section is copied here from the description of
+	&glibtop-get-procmem;.
+      </para>
+	
+      &include-proc-mem.sgml;
+
+    </sect1>
+
+  </chapter>
+
 </book>
 
 <!--