1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<?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., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, 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>
|
