@node White Paper, Reference Manual, About, Top

@chapter LibGTop White Paper

@menu

* Introduction::                Introduction

* Overview::                    Overview

@end menu

@node Introduction, Overview, White Paper, White Paper

@section Introduction

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.

@itemize @bullet

@item

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.

@item

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

@item

Linux has a very nice @file{/proc} filesystem, but reading and parsing

@file{/proc} is very slow and inefficient.

@item

Solaris is a bit better, but you still need to be in the @code{sys} group or

even root to get some data.

@end itemize

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.

@node Overview,  , Introduction, White Paper

@section Overview

This section should give you a short overview on how LibGTop was developed, which

things needed to be considered and how it works.

@menu

* Interface Design::            Things that need to be considered

* Server Implementation::       The LibGTop "server"

@end menu

@node Interface Design, Server Implementation, Overview, Overview

@subsection Interface Design

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.

@node Server Implementation,  , Interface Design, Overview

@subsection Server Implementation

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.