for libgtop Martin Baulig

martin@home-of-linux.org

Germán Poó-Caamaño

gpoo@ubiobio.cl

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, 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 GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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. LibGTop is a library to get system specific data such as CPU and Memory Usage and information about running Processes. 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. 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. 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. 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. 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. 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). Linux has a very nice @file{/proc} filesystem, but reading and parsing @file{/proc} is very slow and inefficient. Solaris is a bit better, but you still need to be in the @code{sys} group or even root to get some data. 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. 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. This section should give you a short overview on how LibGTop was developed, which things needed to be considered and how it works. 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. 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. 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. 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. 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. This section contains the API reference for libgtop. All the public interfaces are documented here.