← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to ksysguard/ksysguardd/Porting-HOWTO

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
ksysguard/ksysguardd/Porting-HOWTO
 
1
This document describes the interface between ksysguard and
 
2
ksysguardd. ksysguardd is started as a child of ksysguard, either
 
3
directly or via a shell. Alternatively a ksysguardd can listen on a
 
4
port and a single instance can then be used by multiple instances of
 
5
ksysguard.
 
6
 
 
7
This client/server design was chosen, because on some operating
 
8
systems the back-end needs elevated permissions.
 
9
It also allowed for an easy network support using existing
 
10
security mechanisms (ssh).
 
11
 
 
12
ksysguard sends commands and ksysguardd answers to them. Each answer
 
13
ends with the string "\nksysguardd> ". Error messages are enclosed in
 
14
ESC '\033' characters. Therefor regular messages may never contain
 
15
ESC. The set of commands that each ksysguardd implementation supports
 
16
can be very different. There are only a very few mandatory command and
 
17
a few recommended commands.
 
18
 
 
19
The mandatory commands are 'monitors', 'test' and 'quit'.
 
20
The recommended commands are:
 
21
 
 
22
cpu/system/idle
 
23
cpu/system/sys
 
24
cpu/system/nice
 
25
cpu/system/user
 
26
mem/swap/free
 
27
mem/swap/used
 
28
mem/physical/cached
 
29
mem/physical/buf
 
30
mem/physical/application
 
31
mem/physical/used
 
32
mem/physical/free
 
33
ps
 
34
pscount
 
35
 
 
36
Without these commands KSysGuard is not very helpful.
 
37
 
 
38
The 'monitors' command returns the list of available sensors. The
 
39
output looks like this:
 
40
 
 
41
--------
 
42
mem/physical/free       integer
 
43
ps      table
 
44
pscount integer
 
45
ksysguardd> 
 
46
--------
 
47
 
 
48
Sensor names can be hierarchical. Each level is separated by a
 
49
/. If you don't want a '/' character to be interpreted as a hierarchy
 
50
delimiter, you can escape it with a preceding '\'. ksysguard uses a tree
 
51
widget in the SensorBrowser to display the commands in a tree. Every
 
52
sensor name must be followed by the type of the sensor separated by a
 
53
tab. Currently 4 different types of sensors are supported, integer,
 
54
float, listview and table. The table sensor returns the information for
 
55
the ProcessController widget. listview sensors use a generic table to
 
56
display information. To find out more about a sensor an additional
 
57
command must be implemented for each sensor that has a questionmark
 
58
appended to the sensor name. It can be used to find out more about the
 
59
sensor.
 
60
 
 
61
--------
 
62
ksysguardd> mem/physical/free?
 
63
Free Memory     0       260708  KB
 
64
ksysguardd>
 
65
--------
 
66
 
 
67
integer and float sensor return a short description, the minimum and
 
68
maximum value and the unit. All fields are again separated by
 
69
tabs. The minimum and maximum values can both be 0 to trigger the
 
70
auto-range feature of the display.
 
71
 
 
72
--------
 
73
ksysguardd> ps?
 
74
Name    PID     PPID    UID     GID     Status  User%   System% Nice    VmSize  VmRss   Login   TracerPID       Command
 
75
s       d       d       d       d       S       f       f       d       D       D       s       d       s
 
76
ksysguardd>
 
77
--------
 
78
 
 
79
This is the output of the ps? inquiry command. The ps command is the
 
80
only recommended command. The answer to ps? consists of 2 lines. Both
 
81
lines have the same number of fields each separated by a tab. The
 
82
first line specifies the name of the columns and the second the type
 
83
of the values in the column.
 
84
 
 
85
d: integer value
 
86
D: integer value that should be localized in the frontend
 
87
f: floating point value
 
88
s: string value
 
89
S: string value that needs to be translated
 
90
   Strings must be added to the ProcessList::columnDict dictionary.
 
91
 
 
92
For the ProcessController to function properly the Name and PID
 
93
columns are mandatory. All other columns are optional and their
 
94
content may be implementation dependant. It is highly recommended not
 
95
to deviate from the Linux implementation unless absolutely
 
96
unavoidable, in order to provide a consistent interface across all
 
97
platforms.
 
98
 
 
99
The 'test' command can be used by the front-end to find out if a
 
100
certain other command is supported by this version of ksysguardd. The
 
101
command returns "1\n" if the command is supported and "0\n" if the
 
102
command is not supported.
 
103
 
 
104
The 'quit' command terminates ksysguardd.
 
105
 
 
106
ksysguardd may support dynamic monitor sets. If a CPU is added or an
 
107
interface disabled, monitors may be added or removed. To notify the
 
108
front-end about this, you need to send the string "RECONFIGURE" over
 
109
stderr. This causes the front-end to request the list of monitors
 
110
again and adapt it's layout accordingly. If ksysguardd receives a
 
111
command it doesn't know it has to reply with "UNKNOWN
 
112
COMMAND\nksysguardd> ".
 
113
 
 
114
ksysguardd does not handle native language support. In order to have a
 
115
minimum installation (only a single file) on the monitored machine,
 
116
all translation are handled by the front-end. Please see the files
 
117
gui/ksgrd/SensorManger.cpp and gui/SensorDisplayLib/ProcessTable.cpp
 
118
if you add new strings.
 
119
 
 
120
/**
 
121
 * Since I'm very much a C++ guy I've written some functions which
 
122
 * provide a similar functionality as template classes for lists and
 
123
 * arrays. The Linux implementation uses them. Feel free to use them for
 
124
 * the ports as well if you like. The interface is described in
 
125
 * CContLib/ccont.h. Unfortunately I still haven't found time to document
 
126
 * it properly, but the use should be fairly obvious.
 
127
 */
 
128
 
 
129
Chris <cs@kde.org>
 
130
 
 
131
Since the above mentioned CContLib was a little slow I reimplement it and
 
132
wrote some docu stuff in the header file. If you need an example for use
 
133
look at ksysguardd/Linux/diskstat.(h|c).
 
134
 
 
135
Tobias <tokoe@kde.org>