source: trunk/third/libgtop/RELNOTES-1.0 @ 18272

Revision 18272, 5.5 KB checked in by ghudson, 22 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r18271, which included commits to RCS files with non-trunk default branches.
Line 
1RELEASE NOTES FOR LIBGTOP 1.0 STABLE
2====================================
3
4OVERVIEW
5--------
6
7LibGTop is a library that read information about processes and the
8running systems. This information include:
9
10General System Information:
11
12cpu             - CPU Usage
13mem             - Memory Usage
14swap            - Swap Usage (including paging activity)
15loadavg         - Load average (including nr_running, nr_tasks, last_pid)
16uptime          - Uptime and Idle time, can be calculated from CPU usage
17
18SYS V IPC Limits:
19
20shm_limits      - Shared Memory Limits
21msg_limits      - Message Queue Limits
22sem_limits      - Semaphore Set Limits
23
24Network:
25
26netload         - Network load
27ppp             - PPP statistics
28
29Process List:
30
31proclist        - List of processes
32
33Process information:
34
35proc_state      - cmd, state, uid, gid
36proc_uid        - uid,euid,gid,egid,pid,ppid,pgrp
37                  session,tty,tpgid,priority,nice
38proc_mem        - size,vsize,resident,share,rss,rss_rlim
39proc_time       - start_time,rtime,utime,stime,cutime,cstime
40                  timeout,it_real_value,frequency
41proc_signal     - signal,blocked,sigignore,sigcatch
42proc_kernel     - k_flags,min_flt,maj_flt,cmin_flt,cmaj_flt
43                  kstk_esp,kstk_eip,nwchan,wchan
44proc_segment    - text_rss,shlib_rss,data_rss,stack_rss,dirty_size
45                  start_code,end_code,start_stack
46
47Process maps:
48
49proc_args       - Command line arguments
50proc_map        - Process map (/proc/<pid>/maps under Linux)
51
52File system usage:
53
54mountlist       - List of currently mounted filesystems
55fsusage         - File system usage
56
57PORTABILITY:
58-----------
59
60LibGTop is designed to be as portable as possible. None of the
61functions and retrieved information should be specific to a specific
62operating system. So you only need to port the system dependent part
63of the library to a new system and all application programs can then
64use libgtop on this new system.
65
66CLIENT/SERVER MODEL:
67-------------------
68
69Some systems like DEC OSF/1 or BSD require special privileges for the
70calling process to fetch the required information (SUID root/SGID
71kmem). To solve this problem, I designed a client/server model which
72makes a call to a SUID/SGID server which fetches the required
73information whenever it is required. This server is only called for
74features that really require privileges, otherwise the sysdeps code
75is called directory (every user can get the CPU usage on DEC OSF/1,
76but only root can get information about processes other than the
77current one).
78
79There is also some kind of daemon which can be used to fetch
80information from remote systems (still experimental). This daemon
81normally runs as nobody and calls the SUID/SGID itself when needed.
82
83LIBGTOP AND GNOME:
84-----------------
85
86LibGTop is currently used in various places in the GNOME Project,
87for instance in some of the applets in gnome-core and - of cause -
88this ultra-cool application called GTop ...
89
90Although LibGTop is not specific to GNOME and under GPL license, I
91spent most my time during the last months to work in the GNOME project
92so this is the primary use for LibGTop (and currently the only one).
93
94However, you can also give its configure.in script the `--without-gnome'
95parameter and then use it fully without GNOME in your own applications.
96
97LIBGTOP AND GNOME - PART II:
98---------------------------
99
100LibGTop was tested with FreeBSD 3.0 but it should also work with
101FreeBSD 2.2.7, NetBSD and OpenBSD.
102
103Currently my primary aim is to help the GNOME people with our 1.0 release
104so I won't have much time to test it with any other system than Linux.
105
106However, I consider FreeBSD, NetBSD and OpenBSD as supported systems for
107LibGTop and whenever I get bug reports I will do my best to fix them as
108quickly as possible.
109
110PLATFORM SPECIFIC NOTES FOR LINUX:
111==================================
112
113Under Linux, LibGTop should work without problems and read everything
114from /proc.
115
116LibGTop 0.25 also had an experimental kernel interface to read this
117information directly from the kernel with a system call - but I have
118currently dropped support for this as I am too busy with GNOME
119development to keep current with kernel hacking.
120
121PLATFORM SPECIFIC NOTES FOR SOLARIS:
122====================================
123
124Since so many people were asking me about this:
125
126LibGTop currently does not have any support for Solaris, and it will
127never have until some volunteer writes the code for it. I can't do this
128myself since I do not have any machine to test it on.
129
130PLATFORM SPECIFIC NOTES FOR BSD:
131=================================
132
133There are a few caveats:
134
135* You need to manually make the `$(prefix)/bin/libgtop_server' SGID to
136  kmem after installation and mount the /proc file system of FreeBSD
137  (/proc/<pid>/mem is used within kvm_uread ()).
138
139* To get the filenames of the process maps displayed in GTop, you need
140  to configure with the `--with-libgtop-inodedb' option (you need GDBM
141  for this to work).
142
143  You have then to create an inode database which is used to look up
144  filenames. This is done using the `mkinodedb' program which comes
145  along with libgtop.
146
147  See the file src/inodedb/README for details:
148
149  The `mkinodedb' program which is build in this directory takes two
150  command line arguments: the full pathname of the database to be
151  created and the name of a configuration file consisting of directory
152  and file names each on a line by itself - see `/etc/ld.so.conf' for
153  an example.
154
155  Putting a directory name in this file means all regular files found
156  in this directory are included in the database, but it will not
157  recursively descend into subdirectories (for instance, we want
158  everything in `/usr/lib' but not every single file in `/usr/lib/sgml').
159  You can also use filenames to include a single file.
160
161Have fun,
162
163Martin <martin@home-of-linux.org>
Note: See TracBrowser for help on using the repository browser.