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