Blame doc/reference/libgtop-docs.xml

Packit d37888
Packit d37888
Packit d37888
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
Packit d37888
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
Packit d37888
  <bookinfo>
Packit d37888
    <title>Libgtop Reference Manual</title>
Packit d37888
    <releaseinfo>for libgtop <xi:include href="version.xml"/></releaseinfo>
Packit d37888
    <authorgroup>
Packit d37888
      <author>
Packit d37888
	<firstname>Martin </firstname>
Packit d37888
	<surname>Baulig</surname>
Packit d37888
	<affiliation>
Packit d37888
	  <address>
Packit d37888
	    <email>martin@home-of-linux.org</email>
Packit d37888
	  </address>
Packit d37888
	</affiliation>
Packit d37888
      </author>
Packit d37888
      <author>
Packit d37888
	<firstname>Germán</firstname>
Packit d37888
	<surname>Poó-Caamaño</surname>
Packit d37888
	<affiliation>
Packit d37888
	  <address>
Packit d37888
	    <email>gpoo@ubiobio.cl</email>
Packit d37888
	  </address>
Packit d37888
	</affiliation>
Packit d37888
      </author>
Packit d37888
    </authorgroup>
Packit d37888
Packit d37888
    <legalnotice>
Packit d37888
      <para>Permission is granted to copy, distribute and/or modify
Packit d37888
      this document under the terms of the <citetitle>GNU Free
Packit d37888
      Documentation License</citetitle>, Version 1.1 or any later
Packit d37888
      version published by the Free Software Foundation with no
Packit d37888
      Invariant Sections, no Front-Cover Texts, and no Back-Cover
Packit d37888
      Texts. You may obtain a copy of the <citetitle>GNU Free
Packit d37888
      Documentation License</citetitle> from the Free Software
Packit d37888
      Foundation by visiting 
Packit d37888
      url="http://www.fsf.org">their Web site</ulink> or by writing
Packit d37888
      to: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Packit d37888
      Boston, MA 02110-1301, USA.</para>
Packit d37888
Packit d37888
      <para>Many of the names used by companies to distinguish their
Packit d37888
      products and services are claimed as trademarks. Where those
Packit d37888
      names appear in any GNOME documentation, and those trademarks
Packit d37888
      are made aware to the members of the GNOME Documentation
Packit d37888
      Project, the names have been printed in caps or initial
Packit d37888
      caps.</para>
Packit d37888
    </legalnotice>
Packit d37888
Packit d37888
    <abstract>
Packit d37888
      <para>
Packit d37888
      LibGTop is a library to get system specific data such as CPU and 
Packit d37888
      Memory Usage and information about running Processes.</para>
Packit d37888
Packit d37888
      <para>On Systems like Solaris or Digital Unix where you need special
Packit d37888
      privileges to get those data, it uses a setuid/setgid server to do 
Packit d37888
      so.</para>
Packit d37888
Packit d37888
      <para>Even if LibGTop is a part of the GNOME desktop environment
Packit d37888
      (@uref{http://www.gnome.org}), the main interface of LibGTop is totally
Packit d37888
      independent from any particular desktop environment, so you can also
Packit d37888
      use it as a standalone library in any piece of GPLed software.</para>
Packit d37888
Packit d37888
      <para>This manual documents the interfaces of the libgtop
Packit d37888
      library and has some short notes to help get you up to speed
Packit d37888
      with using the library.</para>
Packit d37888
    </abstract>
Packit d37888
  </bookinfo>
Packit d37888
Packit d37888
  
Packit d37888
Packit d37888
  <chapter id="libgtop-white-paper">
Packit d37888
    <title>White paper</title>
Packit d37888
Packit d37888
    <sect1 id="libgtop-white-paper-introduction">
Packit d37888
      <title>Introduction</title>
Packit d37888
      <para>Many modern UNIX systems like Solaris, BSD or Digitial Unix 
Packit d37888
      only allow priviledged processes to read information like CPU and 
Packit d37888
      Memory Usage or information about running processes.</para>
Packit d37888
Packit d37888
      <itemizedlist>
Packit d37888
      <listitem><para>
Packit d37888
      BSD, for instance, doesn't have any other way to get those data than reading
Packit d37888
      directly from @file{/dev/kmem} and you need to be in the @code{kmem} group to
Packit d37888
      be able to read this.</para></listitem>
Packit d37888
Packit d37888
      <listitem><para>
Packit d37888
      Other systems, like Digital Unix, allow all users to get things like CPU and
Packit d37888
      Memory statistics, but only root may read information about any process other
Packit d37888
      than the current one (you may not even get information about your own processes
Packit d37888
      if you're not root).</para></listitem>
Packit d37888
Packit d37888
      <listitem><para>
Packit d37888
      Linux has a very nice @file{/proc} filesystem, but reading and parsing
Packit d37888
      @file{/proc} is very slow and inefficient.</para></listitem>
Packit d37888
Packit d37888
      <listitem><para>
Packit d37888
      Solaris is a bit better, but you still need to be in the @code{sys} group or
Packit d37888
      even root to get some data.</para></listitem>
Packit d37888
      </itemizedlist>
Packit d37888
Packit d37888
      <para>
Packit d37888
      Because of this system utilities like @code{ps}, @code{uptime} or @code{top}
Packit d37888
      often are setgid kmem or setuid root. Usually, they're also very specific to
Packit d37888
      the system they're written for and not easily portable to other systems without
Packit d37888
      a lot of work.</para>
Packit d37888
Packit d37888
      <para>
Packit d37888
      This, of cause, becomes a problem for graphical tools like @code{gtop} - making
Packit d37888
      a GTK+ program setgid or even setuid would be a security hole as big as you can
Packit d37888
      drive the entire X11 source code through. For the GNOME project, we also needed
Packit d37888
      some kind of library which provides all the required information in a portable
Packit d37888
      since there's more than just one single program that wants to use them - for
Packit d37888
      instance @code{gtop} and the @code{multiload}, @code{cpumemusage} and
Packit d37888
      @code{netload} panel applets.</para>
Packit d37888
Packit d37888
    </sect1>
Packit d37888
Packit d37888
    <sect1 id="libgtop-white-paper-overview">
Packit d37888
      <title>Overview</title>
Packit d37888
      <para>This section should give you a short overview on how LibGTop
Packit d37888
      was developed, which things needed to be considered and how it 
Packit d37888
      works.</para>
Packit d37888
Packit d37888
      <sect2 id="libgtop-white-paper-overview-design">
Packit d37888
      <title>Interface Design: Things that need to be considered</title>
Packit d37888
      <para>
Packit d37888
At the very beginning, it was necessary to collect all the data the library part
Packit d37888
should provide and put them into some C structures. This was not that easiy as it
Packit d37888
might sound since LibGTop should be portable to any modern UNIX system with a common
Packit d37888
library part on all those systems, but the data that should be returned vary from
Packit d37888
system to system. For instance some systems support shared memory, but some others
Packit d37888
may not.</para>
Packit d37888
Packit d37888
      <para>
Packit d37888
The header files where we define these C structures (which are system-independent) are
Packit d37888
shared between client and server. This way we can call the system dependent code
Packit d37888
directly where we do not need any special privileges to do so.</para>
Packit d37888
Packit d37888
      <para>
Packit d37888
All of those structures contain a @code{flags} member which is interpreted as a bit
Packit d37888
mask and tells the caller of the library functions which of the fields in the returned
Packit d37888
structure are valid and which are not.</para>
Packit d37888
      </sect2>
Packit d37888
Packit d37888
      <sect2 id="libgtop-white-paper-overview-server">
Packit d37888
      <title>Server Implementation: The LibGTop "server"</title>
Packit d37888
      <para>
Packit d37888
The LibGTop @dfn{server} is a setgid/setuid binary which contains all the system
Packit d37888
dependent code which needs special privileges. It is only build if it's required
Packit d37888
on the current system (for instance, the Linux kernel provides all the required
Packit d37888
data via its @file{/proc} filesystem so we do not need the server at all) and it
Packit d37888
only contains the @dfn{features} which need privileges.</para>
Packit d37888
Packit d37888
      <para>
Packit d37888
Whenever we do not need any privileges to get all the data for some of the requested
Packit d37888
structures (here called @dfn{features}) the library calls the sysdeps code directly
Packit d37888
rather than using the server.</para>
Packit d37888
      </sect2>
Packit d37888
    </sect1>
Packit d37888
Packit d37888
  </chapter>
Packit d37888
Packit d37888
  <chapter id="libgtop-lib">
Packit d37888
    <title>Libgtop Library Reference</title>
Packit d37888
Packit d37888
    <para>This section contains the API reference for libgtop.  All
Packit d37888
    the public interfaces are documented here.</para>
Packit d37888
Packit d37888
    <xi:include href="xml/glibtop.xml"/>
Packit d37888
    <xi:include href="xml/close.xml"/>
Packit d37888
    <xi:include href="xml/command.xml"/>
Packit d37888
    <xi:include href="xml/glibtop-server.xml"/>
Packit d37888
    <xi:include href="xml/netload.xml"/>
Packit d37888
    <xi:include href="xml/ppp.xml"/>
Packit d37888
    <xi:include href="xml/shm_limits.xml"/>
Packit d37888
    <xi:include href="xml/uptime.xml"/>
Packit d37888
    <xi:include href="xml/netlist.xml"/>
Packit d37888
    <xi:include href="xml/open.xml"/>
Packit d37888
    <xi:include href="xml/parameter.xml"/>
Packit d37888
    <xi:include href="xml/procargs.xml"/>
Packit d37888
    <xi:include href="xml/procmem.xml"/>
Packit d37888
    <xi:include href="xml/procopenfiles.xml"/>
Packit d37888
    <xi:include href="xml/procsegment.xml"/>
Packit d37888
    <xi:include href="xml/procsignal.xml"/>
Packit d37888
    <xi:include href="xml/sysdeps.xml"/>
Packit d37888
    <xi:include href="xml/procstate.xml"/>
Packit d37888
    <xi:include href="xml/procuid.xml"/>
Packit d37888
    <xi:include href="xml/proctime.xml"/>
Packit d37888
    <xi:include href="xml/signal.xml"/>
Packit d37888
    <xi:include href="xml/procmap.xml"/>
Packit d37888
    <xi:include href="xml/sysinfo.xml"/>
Packit d37888
    <xi:include href="xml/union.xml"/>
Packit d37888
    <xi:include href="xml/version.xml"/>
Packit d37888
    <xi:include href="xml/proclist.xml"/>
Packit d37888
    <xi:include href="xml/sem_limits.xml"/>
Packit d37888
    <xi:include href="xml/prockernel.xml"/>
Packit d37888
    <xi:include href="xml/fsusage.xml"/>
Packit d37888
    <xi:include href="xml/loadavg.xml"/>
Packit d37888
    <xi:include href="xml/mem.xml"/>
Packit d37888
    <xi:include href="xml/mountlist.xml"/>
Packit d37888
    <xi:include href="xml/msg_limits.xml"/>
Packit d37888
    <xi:include href="xml/cpu.xml"/>
Packit d37888
    <xi:include href="xml/swap.xml"/>
Packit d37888
  </chapter>
Packit d37888
</book>