New file - basic documentation for the table () system call.

1998-07-21  Martin Baulig  <martin@home-of-linux.org>

	* table.sgml: New file - basic documentation for the
	table () system call.

6 files changed, 395 insertions, 22 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
index d91096a3..546d7293 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -1,22 +1,10 @@
 *.shml
+*.ced
 .timestamp
 .timestamp2
 .timestamp3
-dbtohtml-1.shtml
-dbtohtml-2.shtml
-dbtohtml-3.shtml
-dbtohtml.shtml
+.timestamp4
 gnome-hackers
-gnome-hackers.ced
 libgtop
-libgtop-1.shtml
-libgtop-2.shtml
-libgtop-3.shtml
-libgtop-4.shtml
-libgtop-5.shtml
-libgtop-INDEX.shtml
 libgtop-ref
-libgtop-ref.ced
-libgtop.ced
-libgtop.fot
-libgtop.shtml
+table
diff --git a/doc/ChangeLog b/doc/ChangeLog
new file mode 100644
index 00000000..bc6f94c0
--- /dev/null
+++ b/doc/ChangeLog
@@ -0,0 +1,4 @@
+1998-07-21  Martin Baulig  <martin@home-of-linux.org>
+
+	* table.sgml: New file - basic documentation for the
+	table () system call.
diff --git a/doc/Makefile b/doc/Makefile
index f020f45a..ec8f2cc3 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,22 +1,37 @@
-all:	.timestamp .timestamp2 .timestamp3
+all:	.timestamp .timestamp2 .timestamp3 .timestamp4
+
+clean:
+	-rm -f .timestamp*
+	-rm -rf libgtop gnome-hackers libgtop-ref table
 
 .timestamp:	libgtop.sgml
-	rm -rf libgtop
+	-rm -rf libgtop
 	mkdir libgtop
-	jade -D /usr/lib/sgml/jade_dsl -d libgtop.dsl -t sgml \
+	-rm -f .timestamp
+	jade -D /usr/lib/sgml -d libgtop.dsl -t sgml \
 		-V %no-make-index% libgtop.sgml > /dev/null && \
 		touch .timestamp
 
 .timestamp2:	gnome-hackers.sgml
-	rm -rf gnome-hackers
+	-rm -rf gnome-hackers
 	mkdir gnome-hackers
-	jade -D /usr/lib/sgml/jade_dsl -d gnome-hackers.dsl -t sgml \
+	-rm -f .timestamp2
+	jade -D /usr/lib/sgml -d gnome-hackers.dsl -t sgml \
 		-V %no-make-index% gnome-hackers.sgml > /dev/null && \
 		touch .timestamp2
 
 .timestamp3:	libgtop-ref.sgml ../guile/reference.sgml
-	rm -rf libgtop-ref
+	-rm -rf libgtop-ref
 	mkdir libgtop-ref
-	jade -D /usr/lib/sgml/jade_dsl -d libgtop-ref.dsl -t sgml \
+	-rm -f .timestamp3
+	jade -D /usr/lib/sgml -d libgtop-ref.dsl -t sgml \
 		-V %no-make-index% libgtop-ref.sgml > /dev/null && \
 		touch .timestamp3
+
+.timestamp4:	table.sgml
+	-rm -rf table
+	mkdir table
+	-rm -f .timestamp4
+	jade -D /usr/lib/sgml -d table.dsl -t sgml \
+		-V %no-make-index% table.sgml > /dev/null && \
+		touch .timestamp4
diff --git a/doc/table.announce.txt b/doc/table.announce.txt
new file mode 100644
index 00000000..8104553e
--- /dev/null
+++ b/doc/table.announce.txt
@@ -0,0 +1,161 @@
+Path: news.uni-stuttgart.de!fu-berlin.de!taurus.uni-trier.DE!baulig
+From: Martin Baulig <baulig@merkur.uni-trier.de>
+Newsgroups: comp.os.linux.development.system
+Subject: RFC: New system call for /proc information ?
+Date: 07 Jun 1998 20:22:47 +0200
+Lines: 143
+Sender: baulig@Taurus.uni-trier.de
+Message-ID: <of7zpfprs08.fsf@Taurus.uni-trier.de>
+NNTP-Posting-Host: taurus.uni-trier.de (136.199.14.201)
+Mime-Version: 1.0
+Content-Type: text/plain; charset=iso-8859-1
+Content-Transfer-Encoding: 8bit
+NNTP-Posting-User: baulig
+X-Access: 16 1542 1543
+X-Trace: fu-berlin.de 897243777 29527 baulig 136.199.14.201
+X-Newsreader: Gnus v5.6.11/XEmacs 20.3 - "Vatican City"
+Xref: news.uni-stuttgart.de comp.os.linux.development.system:73539
+
+[Posted to the Gnome Mailing List and to comp.os.linux.development.system]
+
+Request for Comments:
+====================
+
+Should we have a new system call under Linux which fetches information
+from the /proc filesytem similar to the table() function of DEC OSF/1 ?
+
+The whole story:
+===============
+
+I am currently working on libgtop, a library that fetches information
+from the proc filesystem for user processes. This library uses a suid
+server on system where this is required. On Linux, the information are
+fetched directly from the proc filesystem.
+
+Now, I made some profilings (fetches 50000 times cpu, memory, swap,
+uptime and loadavg):
+
+Each sample counts as 0.01 seconds.
+  %   cumulative   self              self     total           
+ time   seconds   seconds    calls  ns/call  ns/call  name    
+ 91.86    348.03   348.03                             read
+  3.07    359.67    11.64                             open
+  0.67    362.22     2.55                             close
+  0.16    363.55     0.62                             memset
+  0.16    364.14     0.59                             __ipc
+  0.03    368.84     0.12                             vsscanf (iovsscanf.c:31)
+  0.01    374.49     0.05                             sscanf (sscanf.c:28)
+  0.00    378.71     0.01                             semctl (semctl.c:32)
+  0.00    378.73     0.01                             shmctl (shmctl.c:30)
+
+granularity: each sample hit covers 4 byte(s) for 0.00% of 378.88 seconds
+
+index % time    self  children    called     name
+[1]     91.9  348.03    0.00                 read [1]
+-----------------------------------------------
+[2]      3.1   11.64    0.00                 open [2]
+-----------------------------------------------
+[3]      0.7    2.55    0.00                 close [3]
+-----------------------------------------------
+[5]      0.2    0.62    0.00                 memset [5]
+-----------------------------------------------
+[6]      0.2    0.59    0.00                 __ipc [6]
+-----------------------------------------------
+[35]     0.0    0.12    0.00                 vsscanf (iovsscanf.c:31) [35]
+-----------------------------------------------
+[96]     0.0    0.05    0.00                 sscanf (sscanf.c:28) [96]
+-----------------------------------------------
+
+You see, it spends a lot of time in read() which is only used to read the
+data from the files in /proc. Well, basically one can say that these
+timings are not so bad, normally a process periodically fetches those
+information say 10 times a seconds which makes 36000 invocations per
+hour.
+
+This will make a total of about 250 seconds per hour or on even say:
+
+``a program fetching those information at a frequency of 10 will take
+  about 7 % of each hour just for reading files from /proc''.
+
+Now look at timings of __ipc, they're about 350 times better 'cause this
+is done using system calls.
+
+So far so good, now look at how this is done on the DEC OSF/1 port of the
+library (the following code is part of libgtop - GPL/LGPL):
+
+CPU usage:
+{
+	struct tbl_sysinfo sysinfo;
+	int ret;
+	
+	ret = table (TBL_SYSINFO, 0, (char *) &sysinfo, 1,
+		     sizeof (struct tbl_sysinfo)); 
+
+	buf->user = sysinfo.si_user;
+	buf->nice = sysinfo.si_nice;
+	buf->sys  = sysinfo.si_sys;
+	buf->idle = sysinfo.si_idle;
+}
+
+Well, the table() command of DEC OSF/1 has may disadvantages, too - such
+as requiring to be root to fetch any information about processes (well, for
+each process that is not the current one).
+
+But this works using system calls rather that reading and parsing files
+and should be about as fast as getting the IPC information on Linux.
+
+Under Linux, the current trend seems to be to move anything into the /proc
+filesystem, but if you look at the timings, wouldn't it be better to also
+implement a system call interface ?
+
+Don't understand me wrong:
+=========================
+
+I *do not want* to *replace* the /proc filesystem - it's an excellent
+idea to be able to fetch all information on the command line without
+any program just a simple 'cat' - I want to *add* a *new* system call
+to allow programmers to fetch those information faster that reading
+from /proc.
+
+To come to the point:
+=====================
+
+Is there any public interest in having a new system call under Linux
+which can be used to fetch all information that are currently in the
+/proc filesystem.
+
+Basically, this system would be defined like this:
+
+	asmlinkage int
+	sys_table (int command, struct sysinfo_table *buf)
+
+and be invoked like this:
+
+	#include <sys/table.h>
+	
+	{
+	  struct sysinfo_cpu cpu;
+	  struct sysinfo_mem mem;
+	
+	  ret = table (TABLE_CPU, &cpu);
+	  if (ret == -1) return; /* or invoke any error handler */
+	
+	  ret = table (TABLE_MEM, &mem);
+	  if (ret == -1) return;
+	}
+
+What do you think, folks. Should we have such a system call under Linux ?
+I can do the implementation of this system call, but I want to have some
+feedback first.
+
+Martin
+
+-- 
+-----------------------------------------------------------------
+   Martin Baulig - Angewandte Mathematik - Universitaet Trier
+
+   baulig@castor.uni-trier.de, http://www.home-of-linux.com/
+   Key: 1024-bit key with ID C8178435 created 1997/01/24 
+   ID:  67 C1 84 A0 47 F5 11 C5  5F 68 4C 84 99 05 C3 92
+   Finger me for public key or fetch finger.txt from the url above
+------------------------------------------------------------------
diff --git a/doc/table.dsl b/doc/table.dsl
new file mode 100644
index 00000000..74fcf5aa
--- /dev/null
+++ b/doc/table.dsl
@@ -0,0 +1,12 @@
+<!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY dbtohtml.dsl SYSTEM "dbtohtml.dsl" CDATA DSSSL >
+]>
+
+<style-specification id="tabledbotohtml" use="dbtohtml">
+
+(define %output-basename% "table")
+(define %output-directory% "table")
+
+</style-specification>
+
+<external-specification id="dbtohtml" document="dbtohtml.dsl">
diff --git a/doc/table.sgml b/doc/table.sgml
new file mode 100644
index 00000000..58c0b9e2
--- /dev/null
+++ b/doc/table.sgml
@@ -0,0 +1,193 @@
+<!-- $Id$ -->
+
+<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!entity libgtopConf.sh SYSTEM "../libgtopConf.sh" >
+<!entity home-of-linux "http://www.home-of-linux.org/">
+<!entity table-announce-first "&home-of-linux;kernel/table/ANNOUNCE.FIRST">
+<!entity table20-tgz "&home-of-linux;kernel/table/table20.tgz">
+<!entity table21-tgz "&home-of-linux;kernel/table/table21.tgz">
+<!entity news-c-o-l-d-s "comp.os.linux.development.system">
+<!entity libgtop "<productname>libgtop</productname>">
+<!entity table "<function>table ()</function>">
+]>
+<book>
+  <bookinfo>
+    <title>The &table; system call under Linux</title>
+    <authorgroup>
+      <author>
+	<firstname>Martin</firstname>
+	<surname>Baulig</surname>
+	<affiliation>
+	  <address>
+	    <email>martin@home-of-linux.org</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>1998</year>
+      <holder>Martin Baulig</holder>
+    </copyright>
+    
+    <legalnotice>
+
+      <para>
+	This documentation is free software; you can redistribute
+	it and/or modify it under the terms of the GNU General Public
+	License as published by the Free Software Foundation; either
+	version 2 of the License, or (at your option) any later
+	version.
+	
+      <para>
+	This library is distributed in the hope that it will be
+	useful, but WITHOUT ANY WARRANTY; without even the implied
+	warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+	PURPOSE.  See the GNU General Public License for more
+	details.
+
+      <para>
+	You should have received a copy of the GNU General Public
+	License along with this program; if not, write to the Free
+	Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+	MA 02111-1307 USA
+
+      <para>
+	For more details see the file COPYING in the source
+	distribution of LibGTop.</para>
+
+    </legalnotice>
+
+    <abstract>
+      <para>
+	<literal>$Id$</literal>
+
+      <para>
+	Under <productname>Linux</productname>, reading from
+	<filename>/proc</filename> is somehow slow because the data
+	needs to be converted into a stringified representation from
+	the kernel and to be parsed from the application program to
+	get the original data back.
+
+	While doing the <productname>DEC OSF/1</productname> port of
+	&libgtop; I got the idea to add something similar to the &table;
+	function there to the Linux kernel.
+
+	This is what this document is about.
+    </abstract>
+
+  </bookinfo>
+
+  <toc></toc>
+
+  <chapter id="why-not-sysctl">
+    <title>Why not <function>sysctl</function>?</title>
+
+    <para>
+      Some weeks ago, I posted the initial proposal of the project to
+      <ulink url="news:&news-c-o-l-d-s;">&news-c-o-l-d-s;</ulink> with
+      Message-ID <literal>&lt;of7zpfprs08.fsf@Taurus.uni-trier.de&gt;</literal>.
+
+    <para>
+      You can also read this article at my site:
+
+      <itemizedlist>
+	<listitem><para>
+	  <ulink url="&table-announce-first;">&table-announce-first;</ulink>
+      </itemizedlist>
+
+    <para>
+      Some people told me to include all the stuff into
+      <function>sysctl</function> instead of inventing a new system call.
+
+    <para>
+      Basically this is a good idea, but the main problem with
+      <function>sysctl</function> is that this should be applied to standard
+      kernels and not just as a short patch. Well, AFAIK something similar
+      is on the "wish list" for 2.2er kernels - but of cause it'll need some
+      time until we have a real replacement of the <filename>/proc</filename>
+      filesystem in <function>sysctl</function>.
+
+    <para>
+      If someone thinks that this absolutely should be included in
+      <function>sysctl</function>: think about some kind of interface,
+      discuss it with the kernel developers, ...
+
+  <chapter id="about-table">
+    <title>About the &table; function</title>
+
+    <para>
+      Using the &table; function will not affect any existing kernel
+      structures and can be done independent from kernel development.
+
+    <para>
+      So it can easily be used in &libgtop; until we have something
+      simliar in standard kernels.
+
+    <para>
+      If you want to use the &table; function in your own programs, be
+      aware that it is just intended to be some kind of quick solution
+      for &libgtop; until there's something better in standard kernels.
+
+  <chapter id="how-to-use">
+    <title>How to use the &table; function in &libgtop;</title>
+
+    <para>
+      The source code of the &table; function is distributed together with
+      &libgtop;. It can be found in the <filename>kernel/table20</filename>
+      directory for 2.0.xx kernels and in the <filename>kernel/table21</filename>
+      directory for 2.1.xx kernels.
+
+    <para>
+      You can also download it from my site:
+      
+      <itemizedlist>
+	<listitem><para>
+	    <ulink url="&table20-tgz;">&table20-tgz</ulink>
+	    (for kernel 2.0.xx)
+	<listitem><para>
+	    <ulink url="&table21-tgz;">&table21-tgz</ulink>
+	    (for kernel 2.1.xx)
+      </itemizedlist>
+
+    <para>
+      Copy the contents of the appropriate directory to
+      <filename>/usr/src/linux/table</filename>, apply the
+      patch to the kernel and re-configure &libgtop;.
+
+    <para>
+      After that, you can unmount <filename>/proc</filename> and
+      &libgtop; will still work !
+
+      <note>
+	<para>
+	  Maybe one could consider this as a bug, but currently there
+	  isn't a configuration option to disable the &table; function
+	  once you applied the patch ...
+      </note>
+
+      <note>
+	<para>
+	  Currently I'm working on the 2.1.x version to implement some
+	  features newer kernels have - so the 2.0.x version may not
+	  have all features the 2.1.x one has.
+      </note>
+
+      <note>
+	<para>
+	  The 2.1.x version of the &table; function is implemented
+	  as a kernel module. You have to do a
+	  <command>insmod table/module.o</command> manually to use it.
+
+	<para>
+	  This has the advantage that you don't need to reboot if you
+	  want to play around with the code a little bit.
+      </note>
+      
+</book>
+
+<!--
+  Local Variables:
+  mode: sgml
+  sgml-indent-data: t
+  End:
+ -->