|
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>
|