Re: gnome on FreeBSD [procfs]...

[Martin Baulig <martin home-of-linux org>]

Hi all,

[This is a more detailed mail about my libgtop library.]

LibGTop is a library that was designed to fetch all those information
Linux has in its /proc filesystem.

On systems, where fetching those information would require the program
to be SUID root or SGID [k]mem, it automatically starts a 'gtop_server'
which actually does this job.

LibGTop can be used both for the GNOME project and for any other
program that wants those information (like terminal-top). Once a
program has been ported to use libgtop it can be used on any system
libgtop is ported to.

Porting libgtop should not be very hard and is very straightforward.
I'll do this for DEC OSF/1 (where I'm root) and SunOS (if being able
to read /dev/mem and /dev/kmem is really enough).

The latest copy of the library can be found here:

	http://www.home-of-linux.org/gnome/libgtop/

You'll find the following files in this directory (there is also some
DocBook documentation but it's a little bit out of date):

* 'libgtop-current-cvs.cpio.gz':

  Copy of the CVS repository (I have no machine where I can set up
  anon CVS, so I mirror the repository here).

* 'libgtop-current.cpio.gz':

  Current working copy of the library. Like with gnome, do a
  './autogen.sh' to start.

* 'libgtop-current.tar.gz':

  Same like 'libgtop-current.cpio.gz', just a .tar.gz and not a .cpio.gz

* ChangeLog, NEWS, README:

  Should be up to date.

* 'libgtop.sgml', 'libgtop.dsl', 'Makefile':

  DocBook documentation, somehow out of date; look at the 'Makefile' to see
  how to make the .shtml files out of the .sgml

The following information can currently be retrieved:

GENERAL SYSTEM INFORMATION:
==========================

* CPU Usage (glibtop_get_cpu ()):

	N_("Total CPU Time"),
	N_("CPU Time in User Mode"),
	N_("CPU Time in User Mode (nice)"),
	N_("CPU Time in System Mode"),
	N_("CPU Time in the Idle Task"),
	N_("Tick Frequency")

* Memory Usage (glibtop_get_mem ()):

	N_("Total Memory"),
	N_("Used Memory"),
	N_("Free Memory"),
	N_("Shared Memory"),
	N_("Buffers"),
	N_("Cached"),
	N_("User")

* Load Average (glibtop_get_loadavg ()):

	N_("Load Average")

* Swap Space (glibtop_get_swap ()):

	N_("Total Swap Space"),
	N_("Used Swap Space"),
	N_("Free Swap Space")

* System Uptime (glibtop_get_uptime ()):

	N_("Uptime"),
	N_("Idletime")

* Shared Memory Limits (glibtop_get_shm_limits ()):

	N_("Max segment size"),
	N_("Min segment size"),
	N_("Max number of segments"),
	N_("Max shared segments per process"),
	N_("Max total shared memory")

* Message Queue Limits (glibtop_get_msg_limits ()):

	N_("Size in kilobytes of message pool"),
	N_("Number of entries in message map"),
	N_("Max size of message"),
	N_("Default max size of queue"),
	N_("Max queues system wide"),
	N_("Message segment size"),
	N_("Number of system message headers")

* Semaphore Set Limits (glibtop_get_sem_limits ()):

	N_("Number of entries in semaphore map"),
	N_("Max number of arrays"),
	N_("Max semaphores system wide"),
	N_("Number of undo structures system wide"),
	N_("Max semaphores per array"),
	N_("Max ops per semop call"),
	N_("Max number of undo entries per process"),
	N_("sizeof struct sem_undo"),
	N_("Semaphore max value"),
	N_("Adjust on exit max value")

* Process List (glibtop_get_proclist ()):

	N_("Number of list elements"),
	N_("Total size of list"),
	N_("Size of a single list element")

DETAILED INFORMATION ABOUT PROCESSES:
====================================

* Process state (glibtop_get_proc_state ()):

	N_("Basename of executable file in call to exec()"),
	N_("Single-Char code for process state (S=sleeping)"),
	N_("UID of process"),
	N_("GID of process")

* Process UID/GID and TTY (glibtop_get_proc_uid ()):

	N_("User ID"),
	N_("Effective User ID"),
	N_("Group ID"),
	N_("Effective Group ID"),
	N_("Process ID"),
	N_("PID of parent process"),
	N_("Process group ID"),
	N_("Session ID"),
	N_("Full device number of controlling terminal"),
	N_("Terminal process group ID"),
	N_("Kernel scheduling priority"),
	N_("Standard unix nice level of process")

* Process memory (glibtop_get_proc_mem ()):

	N_("Total # of pages of memory"),
	N_("Number of pages of virtual memory"),
	N_("Number of residnet set (non-swapped) pages"),
	N_("Number of pages of shared (mmap'd) memory"),
	N_("Number of pages the process has in real memory, minus 3 "
	   "for administrative purposes. This is just the pages which "
	   "count towards text, data, or stack space. This does not "
	   "include pages which have not been demand-loaded in, or which "
	   "are swapped out."),
	N_("Current limit in bytes on the rss of the process "
	   "(usually 2,147,483,647).")

* Process timings (glibtop_get_proc_time ()):

	N_("Start time of process in seconds since the epoch"),
	N_("user-mode CPU time accumulated by process"),
	N_("kernel-mode CPU time accumulated by process"),
	N_("cumulative utime of process and reaped children"),
	N_("cumulative stime of process and reaped children"),
	N_("The time (in jiffies) of the process's next timeout"),
	N_("The time (in jiffies) before the next SIGALRM is sent "
	   "to the process due to an interval timer.")

* Process signal masks (glibtop_get_proc_signal ()):

	N_("Mask of pending signals"),
	N_("Mask of blocked signals"),
	N_("Mask of ignored signals"),
	N_("Mask of caught signals")

* Process kernel flags (glibtop_get_proc_kernel ()):

	/* K_Flags */
	N_("Kernel flags of the process.\n\n"
	   "On Linux, currently every flag has the math bit set, because "
	   "crt0.s checks for math emulation, so this is not included in "
	   "the output.\n\n"
	   "This is probably a bug, as not every process is a compiled C "
	   "program.\n\n"
	   "The math bit should be a decimal 4, and the traced bit is "
	   "decimal 10."),
	/* Min_Flt */
	N_("The number of minor faults the process has made, those which "
	   "have not required loading a memory page from disk."),
	/* Maj_Flt */
	N_("The number of major faults the process has made, those which "
	   "have required loading a memory page from disk."),
	/* CMin_Flt */
	N_("The number of minor faults that the process and its children "
	   "have made."),
	/* CMaj_Flt */
	N_("The number of major faults that the process and its children "
	   "have made."),
	/* KStk_ESP */
	N_("The current value of esp (32-bit stack pointer), as found in "
	   "the kernel stack page for the process."),
	/* KStk_EIP */
	N_("The current EIP (32-bit instruction pointer)."),
	/* WChan */
	N_("This is the \"channel\" in which the process is waiting.  This "
	   "is the address of a system call, and can be looked up in a "
	   "namelist if you need a textual name.  (If you have an up-to-date "
	   "/etc/psdatabase, then try ps -l to see the WCHAN field in action)")

* Process segments (glibtop_get_proc_segment ()):

	N_("Text resident set size"),
	N_("Shared-Lib resident set size"),
	N_("Data resident set size"),
	N_("Dirty pages"),
	N_("Address of beginning of code segment"),
	N_("Address of end of code segment"),
	N_("Address of the bottom of stack segment")

LibGTop consists of the following libraries and executables:

* lib/libgtop.la:

  High-level interface which user programs should use, on systems where
  fetching the requested information would require the program to be
  SUID root or SGID [k]mem, the request is passed to
  'src/server/gtop_server'.

* src/server/gtop_server:

  Server program that is SUID root or SGID [k]mem on systems where this
  is required. It is automatically invoked from 'lib/libgtop.la' at the
  time of the first request a program makes.

* sysdeps/<system>/libgtop_sysdeps.la:

  Low-level interface. Defines exactly the same functions than
  'lib/libgtop.la' but fetches those information directly rather than
  connecting to the server.

  The server is linked with this library. On Linux, user programs can use
  it, too. This would speed up the programm a little bit (a little bit -
  the server is only started once per program and reads/writes binary data).

  Currently the following <system>s are supported (I'll port the library
  to those systems myself):

  # linux:	Linux			- Uses the /proc filesystem
  # osf1:	DEC OSF/1 V3.0/3.2	- needs server to be SUID root;
					  under construction
  # sun4:	SunOS 4.1.3		- needs server to be SGID root;
					  not yet started porting
  # stub:	<nothing>		- stub for systems the library is
					  not yet ported on

* sysdeps/names/libgtop_names.la:

  Structure names, labels and descriptions. Normally not needed for user
  programs.

* sysdeps/guile/libgtop_guile.la:

  Guile interface to the library (examples/third):

	guile> (glibtop-get-cpu)
	(63 347460 26177 0 20451 300832 100)
	guile> (glibtop-get-cpu)
	(63 351583 26395 0 20476 304712 100)
	guile> (glibtop-get-mem)
	(127 31715328 30998528 716800 10182656 335872 5906432 20480000)
	guile> (glibtop-get-swap)
	(7 133885952 13791232 120094720)
	guile> (glibtop-get-uptime)
	(3 3524.55 3055.79)
	guile> (glibtop-get-loadavg)
	(1 0.03 0.02 0.07)
	guile> (glibtop-get-shm_limits)
	(31 33554432 1 128 128 4194304)
	guile> (glibtop-get-msg_limits)
	(127 2048 16384 4056 16384 128 16 16384)
	guile> (glibtop-get-sem_limits)
	(1023 4096 128 4096 4096 32 32 32 20 32767 16383)
	guile> (glibtop-get-proclist)
	(7 54 4 216 1 2 3 899 11357 11341 8 48 81 83 153 157 168 171 172 173
	 174 175 176 179 11315 24965 24966 24993 900 188 11344 901 11347
	 11352 534 480 574 737 581 644 738 744 585 740 742 659 896 2304 902
	 903 904 935 1086 11362 11363 11364 24058 24075)

	guile> (glibtop-get-proc_state (getpid))
	(15 "third_linux" #\R 505 100)
	guile> (glibtop-get-proc_uid (getpid))
	(4095 505 505 100 100 24993 24075 24993 24075 1218 24993 5 0)
	guile> (glibtop-get-proc_mem (getpid))
	(63 336 1888256 336 207 336 2147483647)
	guile> (glibtop-get-proc_time (getpid))
	(127 351265 53 4 0 0 0 0)
	guile> (glibtop-get-proc_signal (getpid))
	(15 0 0 2147483647 1218)
	guile> (glibtop-get-proc_kernel (getpid))
	(255 1048576 154 325 0 0 3221210808 1074906868 0)
	guile> (glibtop-get-proc_segment (getpid))
	(127 8 0 328 129 134512640 134540231 3221222748)

* sysdeps/guile/names/libgtop_guile_names.la:

	Guile interface to 'sysdeps/names/libgtop_names.la' (examples/third):

	guile> (glibtop-names-cpu)
	("total" "user" "nice" "sys" "idle" "frequency")
	guile> (glibtop-names-mem)
	("total" "used" "free" "shared" "buffer" "cached" "user")
	guile> (glibtop-names-swap)
	("total" "used" "free")
	guile> (glibtop-names-loadavg)
	("loadavg")
	guile> (glibtop-names-uptime)
	("uptime" "idletime")
	guile> (glibtop-names-shm_limits)
	("shmmax" "shmmin" "shmmni" "shmseg" "shmall")
	guile> (glibtop-names-msg_limits)
	("msgpool" "msgmap" "msgmax" "msgmnb" "msgmni" "msgssz" "msgtql")
	guile> (glibtop-names-sem_limits)
	("semmap" "semmni" "semmns" "semmnu" "semmsl" "semopm" "semume"
	 "semusz" "semvmx" "semaem")
	guile> (glibtop-names-proclist)
	("number" "total" "size")
	guile> (glibtop-names-proc_state)
	("cmd" "state" "uid" "gid")
	guile> (glibtop-names-proc_uid)
	("uid" "euid" "gid" "egid" "pid" "ppid" "pgrp" "session" "tty"
	 "tpgid" "priority" "nice")
	guile> (glibtop-names-proc_mem)
	("size" "vsize" "resident" "share" "rss" "rss_rlim")
	guile> (glibtop-names-proc_time)
	("start_time" "utime" "stime" "cutime" "cstime" "timeout"
	 "it_real_value")
	guile> (glibtop-names-proc_signal)
	("signal" "blocked" "sigignore" "sigcatch")
	guile> (glibtop-names-proc_kernel)
	("k_flags" "min_flt" "maj_flt" "cmin_flt" "cmaj_flt" "kstk_esp"
	 "kstk_eip" "wchan")
	guile> (glibtop-names-proc_segment)
	("trs" "lrs" "drs" "dt" "start_code" "end_code" "start_stack")

* examples/first:

  Shows all information that can currently be fetched.

* examples/first_static:

  Statically linked version of 'examples/first'.

* examples/first_linux:

  Statically linked with 'libgtop_sysdeps.la' (in the correct directory) -
  this one does not use the server and will only work if you invoke it as
  root on systems like DEC OSF/1.

* examples/second [and '_static', '_linux' like above]:

  Dumps information about all currently running processes.

* examples/third [and '_static', '_linux' like above]:

  Guile interface to the library.

Well, I just began with this project some weeks ago, so it still may be
buggy, documentation is not yet written, interfaces may change ..., but
I always like to have some feedback about it.

Martin

-- 
----------------------------------------------------------------
   Martin Baulig - Angewandte Mathematik - Universitaet Trier
   
   baulig@castor.uni-trier.de, http://www.home-of-linux.org/
   Key: 1024-bit key with ID C8178435 created 1997/01/24 
   ID:  67 C1 84 A0 47 F5 11 C5  5F 68 4C 84 99 05 C3 92
   Finger baulig@math38 or fetch mykey.asc from the url above
-----------------------------------------------------------------