oxmc/libgtop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moved doc' and guile' subdirectories into the libgtop-docu module.

Browse Source
This commit is contained in:
Martin Baulig
1998-12-08 23:23:52 +00:00
parent cd7ca97fc5
commit 3da3f1b03f
26 changed files with 0 additions and 5430 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/.cvsignore
View File

@@ -1,8 +0,0 @@
Makefile.in
Makefile
gnome-hackers
libgtop
libgtop-ref
table
*.ced
*.fot

25
doc/ChangeLog
View File

@@ -1,25 +0,0 @@
1998-10-12 Martin Baulig <martin@home-of-linux.org>
* Makefile.am: New file. We are now using automake here.
* libgtopConf.sh: Removed. Since libgtop-docu now requires
LibGTop to be installed we use the installed version of this file.
* Makefile: Removed.
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.
* autoconf.sgml: New file, included from `gnome-hackers.sgml'.
1998-07-21 Martin Baulig <martin@home-of-linux.org>
* gnome-hackers.sgml: Added note that this file is
currently out of date and a link to the documentation
of the table () function.
* table.sgml: New file - basic documentation for the
table () system call.

53
doc/Makefile.am
View File

@@ -1,53 +0,0 @@
htmldir = $(prefix)/html
html_subdirs = libgtop gnome-hackers libgtop-ref table
# Well, yes - you are using GNU Make, aren't you ... ?
stamp_FILES = $(addsuffix .stamp,$(html_subdirs))
sgml_FILES = $(addsuffix .sgml,$(html_subdirs))
dsl_FILES = $(addsuffix .dsl,$(html_subdirs))
EXTRA_DIST = $(sgml_FILES) $(dsl_FILES) dbtohtml.dsl autoconf.sgml
noinst_DATA = $(stamp_FILES)
CLEANFILES = $(stamp_FILES)
distclean-local:
-rm -rf $(html_subdirs)
libgtop.sgml: libgtopConf.sh
gnome-hackers.sgml: autoconf.sgml $(top_builddir)/guile/reference.sgml \
features/uptime.sgml features/uptime.txt features/proclist.sgml \
features/procmem.sgml
libgtopConf.sh:
@LN_S@ `@LIBGTOP_CONFIG@ --config`
# You can set the $(JADE_FLAGS) in your shell to pass additional
# arguments like `-D /usr/lib/sgml' to jade.
SUFFIXES = .stamp .sgml
.sgml.stamp:
echo rm -f $@
-rm -rf $*
mkdir $*
jade $(JADE_FLAGS) -D $(srcdir) -D . -D $(top_builddir)/guile \
-d $(srcdir)/$*.dsl -t sgml -V %no-make-index% $< \
> /dev/null && touch $@
install-data-local:
$(mkinstalldirs) $(htmldir)
for subdir in $(html_subdirs) ; do \
$(mkinstalldirs) $(htmldir)/$$subdir ; \
for file in $$subdir/* ; do \
$(INSTALL_DATA) $$file $(htmldir)/$$subdir ; \
done \
done
dist-hook:
mkdir $(distdir)/features
cp -p $(srcdir)/features/*.sgml $(distdir)/features
cp -p $(srcdir)/features/*.txt $(distdir)/features

253
doc/autoconf.sgml
View File

@@ -1,253 +0,0 @@
<sect1 id="macros">
<title>Autoconf macros</title>
<para>
All you need to check for &libgtop; is in &gnome-libgtop-check.m4;,
just use <function>GNOME_INIT_LIBGTOP</function> with an optional
<parameter>fail</parameter> argument in the same way like
<function>GNOME_INIT</function>:
<example>
<title>Warn if &libgtop; cannot be found</title>
<programlisting>GNOME_INIT_LIBGTOP</programlisting>
</example>
<example>
<title>Abort if &libgtop; cannot be found</title>
<programlisting>GNOME_INIT_LIBGTOP(fail)</programlisting>
</example>
<para>
This will define a <function>HAVE_LIBGTOP</function> automake
conditional and everything from the configuration script of
&libgtop;.
<sect1 id="libgtopConf.sh">
<title>The configuration script of &libgtop; (&libgtopConf.sh;)</title>
<para>
After a successful build of &libgtop;, a &libgtopConf.sh; script
containing useful configuration variables is created.
<para>
It defines the following variables which you can use in your
<filename>Makefile.am</filename>:
<variablelist>
<varlistentry>
<term><parameter>LIBGTOP_LIBDIR</parameter></term>
<listitem>
<para>
The directory where the library files of &libgtop; are installed.
<varlistentry>
<term><parameter>LIBGTOP_INCLUDEDIR</parameter></term>
<listitem>
<para>
The directory where the header files of &libgtop; are installed.
<varlistentry>
<term><parameter>LIBGTOP_LIBS</parameter></term>
<listitem>
<para>
Use this to link your program with &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_INCS</parameter></term>
<listitem>
<para>
Use this to get the header files for &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_NAMES_LIBS</parameter></term>
<listitem>
<para>
Use this to link your program with &libgtop; and its
names interface.
<varlistentry>
<term><parameter>LIBGTOP_NAMES_INCS</parameter></term>
<listitem>
<para>
Use this to get the header files for &libgtop; and the
required <literal>-DGLIBTOP_NAMES</literal> to get its
names interface.
<varlistentry>
<term><parameter>LIBGTOP_GUILE_LIBS</parameter></term>
<listitem>
<para>
Use this to link your program with &libgtop; and its
guile interface. This will also include all the required
guile libraries.
<varlistentry>
<term><parameter>LIBGTOP_GUILE_INCS</parameter></term>
<listitem>
<para>
Use this to get the header files for &libgtop; and guile
and the required <literal>-DGLIBTOP_GUILE</literal> to get
the guile interface of &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_GUILE_NAMES_LIBS</parameter></term>
<listitem>
<para>
Use this to link your program with &libgtop; and both its
names and its guile interface. This will also include all the
required guile libraries.
<varlistentry>
<term><parameter>LIBGTOP_GUILE_NAMES_INCS</parameter></term>
<listitem>
<para>
Use this to get the header files for &libgtop;, its guile
and its names interface, the guile header files and the
required <literal>-DGLIBTOP_GUILE</literal> and
<literal>-DGLIBTOP_NAMES</literal>.
<varlistentry>
<term><parameter>LIBGTOP_BINDIR</parameter></term>
<listitem>
<para>
The directory where the binaries of &libgtop; are installed.
<varlistentry>
<term><parameter>LIBGTOP_SERVER</parameter></term>
<listitem>
<para>
Full pathname of the &libgtop; server.
<varlistentry>
<term><parameter>LIBGTOP_MAJOR_VERSION</parameter></term>
<listitem>
<para>
Major version of &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_MINOR_VERSION</parameter></term>
<listitem>
<para>
Minor version of &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_VERSION</parameter></term>
<listitem>
<para>
Full version of &libgtop;.
<varlistentry>
<term><parameter>LIBGTOP_SERVER_VERSION</parameter></term>
<listitem>
<para>
Version of the &libgtop; server. This is incremented each
time the client/server protocol changes.
<varlistentry>
<term><parameter>libgtop_sysdeps_dir</parameter></term>
<listitem>
<para>
The sysdeps directory that is used on your system.
<varlistentry>
<term><parameter>libgtop_need_server</parameter></term>
<listitem>
<para>
Either <literal>yes</literal> or <literal>no</literal>.
<varlistentry>
<term><parameter>libgtop_use_machine_h</parameter></term>
<listitem>
<para>
Either <literal>yes</literal> or <literal>no</literal>.
Intended for <emphasis>internal use only</emphasis>
and may be removed in future versions.
<note>
<title>Note for &libgtop; hackers</title>
<para>
This variable gets set in
<filename>macros/gnome-libgtop-sysdeps.m4</filename>.
<para>
If this is enabled, you need to put a
<filename>glibtop_machine.h</filename> header file in the
sysdeps directory which needs to define a structure of
type <type>glibtop_machine</type>.
<para>
This structure represents the
<structfield>machine</structfield> field of
<type>glibtop</type> defined in
<filename>glibtop.h</filename>
and can be used to store some
machine dependent data.
</note>
<varlistentry>
<term><parameter>libgtop_guile_found</parameter></term>
<listitem>
<para>
Either <literal>yes</literal> or <literal>no</literal>.
<varlistentry>
<term><parameter>libgtop_want_examples</parameter></term>
<listitem>
<para>
Considered obsolete.
</variablelist>
<para>
All this variables are taken from the
&libgtopConf.sh; script which is created during
the installation of &libgtop;.
<example>
<title>
Sample &libgtopConf.sh; (gnome and guile are installed in
<filename>/home/baulig/INSTALL</filename> and &libgtop; in
<filename>/home/norwegen/TEST</filename>)
</title>
<programlisting>&example-libgtopConf-sh;</programlisting>
</example>
</sect1>
<!--
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" "chapter" "")
End:
-->

3
doc/catalog
View File

@@ -1,3 +0,0 @@
PUBLIC "-//James Clark//DTD DSSSL Flow Object Tree//EN" "fot.dtd"
PUBLIC "ISO/IEC 10179:1996//DTD DSSSL Architecture//EN" "dsssl.dtd"
PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" "style-sheet.dtd"

1627
doc/dbtohtml.dsl
View File

File diff suppressed because it is too large Load Diff

153
doc/features/proclist.sgml
View File

@@ -1,153 +0,0 @@
<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:
-->

103
doc/features/procmem.sgml
View File

@@ -1,103 +0,0 @@
<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:
-->

23
doc/features/uptime.sgml
View File

@@ -1,23 +0,0 @@
<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:
-->

40
doc/features/uptime.txt
View File

@@ -1,40 +0,0 @@
#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;
}

12
doc/gnome-hackers.dsl
View File

@@ -1,12 +0,0 @@
<!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbtohtml.dsl SYSTEM "dbtohtml.dsl" CDATA DSSSL >
]>
<style-specification id="gnomehackersdbotohtml" use="dbtohtml">
(define %output-basename% "gnome-hackers")
(define %output-directory% "gnome-hackers")
</style-specification>
<external-specification id="dbtohtml" document="dbtohtml.dsl">

187
doc/gnome-hackers.sgml
View File

@@ -1,187 +0,0 @@
<!-- $Id$ -->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!-- Site-specific entities, change them if you want to copy this
document somewhere else. -->
<!entity home-of-linux "http://www.home-of-linux.org/">
<!-- Some general entities -->
<!entity libgtop "<productname>libgtop</productname>">
<!-- 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'. -->
<!entity example-libgtopConf-sh SYSTEM "libgtopConf.sh">
<!-- Some entities to include other files. -->
<!entity include-autoconf.sgml SYSTEM "autoconf.sgml">
<!entity include-reference.sgml SYSTEM "reference.sgml">
<!-- The following entities are used in the automatically generated
`reference.sgml' to include custom descriptions of the features.
-->
<!entity include-cpu.sgml "">
<!entity include-mem.sgml "">
<!entity include-swap.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 SYSTEM "features/proclist.sgml">
<!entity include-proc-state.sgml "">
<!entity include-proc-uid.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 "">
<!entity include-proc-segment.sgml "">
<!entity include-proc-map.sgml "">
<!entity include-mountlist.sgml "">
<!entity include-fsusage.sgml "">
<!entity include-uptime.txt SYSTEM "features/uptime.txt">
]>
<book>
<bookinfo>
<title>Using Libgtop in the Gnome Project</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>
This is a short introduction in how to use
<productname>libgtop</productname> in the GNOME project.
It describes the additional options <filename>configure</filename>
takes and the information stored in the automatically generated
<filename>libgtopConf.sh</filename> configuration script.
<note>
<para>
Documentation about the new <function>table ()</function>
function can be found here:
<itemizedlist>
<listitem><para>
<ulink url="&home-of-linux;kernel/table/">
&home-of-linux;kernel/table/
</ulink>
</itemizedlist>
</note>
</abstract>
</bookinfo>
<toc></toc>
<chapter id="autoconf-automake">
<title>Configuration</title>
&include-autoconf.sgml;
</chapter>
<chapter id="functions">
<title>Function Reference List</title>
&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>
<!--
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
End:
-->

12
doc/libgtop-ref.dsl
View File

@@ -1,12 +0,0 @@
<!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbtohtml.dsl SYSTEM "dbtohtml.dsl" CDATA DSSSL >
]>
<style-specification id="libgtoprefdbtohtml" use="dbtohtml">
(define %output-basename% "libgtop-ref")
(define %output-directory% "libgtop-ref")
</style-specification>
<external-specification id="dbtohtml" document="dbtohtml.dsl">

108
doc/libgtop-ref.sgml
View File

@@ -1,108 +0,0 @@
<!-- $Id$ -->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity include-reference.sgml SYSTEM "../guile/reference.sgml" >
<!-- The following entities are used in the automatically generated
`reference.sgml' to include custom descriptions of the features.
-->
<!entity include-cpu.sgml "">
<!entity include-mem.sgml "">
<!entity include-swap.sgml "">
<!entity include-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-proc-state.sgml "">
<!entity include-proc-uid.sgml "">
<!entity include-proc-mem.sgml "">
<!entity include-proc-time.sgml "">
<!entity include-proc-signal.sgml "">
<!entity include-proc-kernel.sgml "">
<!entity include-proc-segment.sgml "">
<!entity include-proc-map.sgml "">
<!entity include-mountlist.sgml "">
<!entity include-fsusage.sgml "">
]>
<book>
<bookinfo>
<title>LibGTop Reference Manual</title>
<authorgroup>
<author>
<firstname>Martin</firstname>
<surname>Baulig</surname>
<affiliation>
<address>
<email>martin@home-of-linux.org</email>
</address>
</affiliation>
</author>
</authorgroup>
<abstract>
<para>
<literal>$Id$</literal>
<para>
This reference manual is automatically generated from
<filename>doc/make-docbook.scm</filename>. It uses the
guile interface of <productname>libgtop</productname> to
get the names of all features the library defines and a
description of the structures.
</abstract>
<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>
</bookinfo>
<toc></toc>
<chapter id="functions">
<title>Function Reference List</title>
&include-reference.sgml;
</book>
<!--
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
End:
-->

12
doc/libgtop.dsl
View File

@@ -1,12 +0,0 @@
<!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbtohtml.dsl SYSTEM "dbtohtml.dsl" CDATA DSSSL >
]>
<style-specification id="libgtopdbtohtml" use="dbtohtml">
(define %output-basename% "libgtop")
(define %output-directory% "libgtop")
</style-specification>
<external-specification id="dbtohtml" document="dbtohtml.dsl">

1332
doc/libgtop.sgml
View File

File diff suppressed because it is too large Load Diff

161
doc/table.announce.txt
View File

@@ -1,161 +0,0 @@
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
------------------------------------------------------------------

12
doc/table.dsl
View File

@@ -1,12 +0,0 @@
<!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">

193
doc/table.sgml
View File

@@ -1,193 +0,0 @@
<!-- $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:
-->