			This is the README file for 


                        X   X  M     M  EEEEEE  M     M
                         X X   MM   MM  E       MM   MM
                          X    M M M M  EEEEEE  M M M M
                         X X   M  M  M  E       M  M  M
                        X   X  M     M  EEEEEE  M     M                            

                        X      M        Emory   Monitor (c) 1996 Robert Gasch


1) Author & Copyright

	xmem was written by Robert Gasch (Robert_Gasch@peoplesoft.com) and is 
	copyright by the author.
	xmem is available from various FTP sites as well as the author's 
        home page, which is:
                http://www.peoplesoft.com/peoplepages/g/robert_gasch/index.htm


2) Distribution Policy

 	Permission to use, copy, modify and distribute this software for
	any purpose and without fee is hereby granted, provided that this
	copyright notice appear in all copies as well as supporting 
	documentation. All work developed as a consequence of the use of 
	this program should duly acknowledge such use.

	See the GNU General Public Licence (included in the file "Copying") 
	for more information.

3) Guarantees

	xmem should work all right *but*

	No representations are made about the suitability of this software 
	for any purpose. This software is provided "as is" without express 
	or implied warranty.

4) What is xmem?

	xmem stands for X Memory Monitor and runs under MIT's X11
	window system. It is a tool designed to make monitoring your 
	memory usage easy by displaying a simple bar graph for both 
	real and virtual memory. It updates the memory statistics at 
	regular, user definable intervals.

5) Version Number

	The current version number is 1.02

6) What if you change the program?

	If you extend xmem's functionality, add support for new UNIX
	flavors, or simply solve bugs, *please*mail* me the changes(!)
	as I'd like to act as the central source for xmem. This will 
	also enable me to include your changes in a future release. 
	Unless it is generic please enclose it in a meaningful
	#ifdef. If your change affects *many* lines, please provide
	some method of me finding it back (preferrably a #ifdef, 
	alternativeley some comment I can grep for). 

	I currently only have access to my home Linux box. If you 
	feel that xmem is useful and have access to another type 
	of system, it should be easy to adapt. All the memory statistics 
	are gathered in get_meminfo() (in xmem_util.c). You should not 
	have to change anything outside of get_meminfo() to port xmem 
	to another OS. 

7) Systems currently supported

	Linux (old (1.2) and new (2.0) kernels )

8) How do I get started?

	This section assumes that you have all the necessary files. (The 
	file "Manifest" contains a list of distributed files.)

	a) Customize the Imakefile to suit your system setup. 

	b) Make the Makefile by typing 
		xmkmf
	If your system does not support generating makefiles from 
	Imakefiles use "Makefile.std" as a template to build your
	own. 

	c) If your X headers do not define APP_DEFAULTS_DIR and your default 
	X Resource file is not 
		/usr/X11R5/lib/X11/app-defaults/
	edit xmem.c and modify the definition for APP_DEFAULTS_DIR. On 
	most systems things should be OK the way they are, but this gives 
	you the possibility to customize this.

	d) Once you have a valid Makefile (see step a&b) build xmem by typing
		make

	Once you have created the executable, you're ready to go. The
	executable will be created in the directory in which the source
	for xmem resides. 

9) Brief users guide

	In this section the following abbreviations are used:
		LB	- left mouse button

	You can get a list of supported options by typing one of the
	following:
		xmem -?
		xmem -help
		xmem help

	Once you have started xmem, you will get a window containing 
	1 or 2 bar graphs (real and virtual memory).  

	If you click on the bar graph of a memory area (LB) you get a 
	window displaying the detailed statistics for the memory area. 
	Clicking on the bar graph again (LB) or clicking in the 
	detail window (LB), closes the detail window while clicking 
	on another bar graph (LB) while the detail window is open, 
	displays this memory area's statistics in the detail window. 
	
	The right mouse button is used to toggle the display mode. The
	default startup mode graphs all memory areas relative to their
	size. By clicking with the right mouse button in any of the 
	windows, the graphs are drawn in absolute size. Clicking (RB) 
	again, reverts back to the original mode. 

	The following keys can be used to control xmem:
		q - quit xmem
		u - update now
		t - toggle display mode
		c - close the detail window

	Specifying the -menu option, will display 2 menu buttons: 
		Update Now - updates all files systems' statistics now
		Quit       - exits xmem

	The Detail Window can display the following statistics. Depending
	on the system you are on, you may not get all these statistics:
		Available		Total Memory Available
		Used			Memory in use
		Free			Free Memory
		Shared			Shared Memory
		Buffer			Buffer Memory

10) How does xmem calculate free space?

	Linux: On Linux, free memory is used as a disk buffer cache. xmem
	will add free memory + buffer memory and use this figure as 
	the free memory for drawing it's usage bar. This is probably not 
	100% accurate, but it will at least give a good idea. 

11) Command line parameters

	xmem accepts the following parameters as command line options:

	+rv                     reverse video (use to override xrdb entry) 
	+synchronous            syncronous mode (use to override xrdb entry)
	-?                      help
	-a                      absolute display mode
	-background <arg>       backgound color 
	-b                      black bars (disable gray fill)
	-bg <arg>               same as -background 
	-bordercolor <arg>      border color
	-borderwidth <arg>      border width
	-detailgeometry <arg>   Geometry of detail window. Only X and Y are 
					honoured
	-display                display
	-fg <arg>               same as -forground
	-font <arg>             font
	-foreground <arg>       forground color (also file system bar color)
	-geometry <arg>         geometry (will override extreme window sizes to 
					apply reasonable settings)
	-help                   help
	-i <arg>                interval at which stats are updated(default=60s)
	-iconic                 iconic
	-m                      minimize window size
	-mb                     draw menu borders
	-menu                   show the menu
	-name <arg>             run xmem under this name
	-p                      don't display percentages
	-r                      display space with respect to root
	-rs <arg>               specify the amount of space reserved for root
	-rv                     reverse video
	-synchronous            synchronous mode
	-v                      verbose
	-w <arg>                display warning pixmap when (real) memory usage 
					reaches <arg> %
	-xrm                    set an entry in the resource database for this
					execution only
	help                    help

12) XResources 

        xmem recognizes the following XResources. Usually xmem will search 
	for resources under the program name but you can override this with 
	the -name flag. If you do not wish to use a specific application 
	defaults file, you can execute xrdb -merge to merge your resource 
	specifications into the XResource database. 

	xmem first checks in the directory pointed at by the environment 
	variable XAPPLRESDIR. If this doesn't yield any resource definitions 
	it checks the APP_DEFAULTS_DIR. This is defined in your headers or 
	in xmem.h. If you want to change this you'll have to recompile xmem.

	absolute		absolute display mode
	background		universal backgound color
	<memory>.background	background color for a file system
	borderColor		border color
	borderWidth		border width
	detailWin.geometry	Geometry of detail window. Only X and Y are
					honored
	detailWin.share		have detail window share file system color
	display			display
	font			font
	foreground		universal foreground color 
	<filesystem>.foreground	foreground color for a file system
	fs_border		do we draw a borders around file systems?
	gray			black bars
	help			show help
	mainWin.geometry	main window geometry
	iconic			start program in iconic mode 
	minimize		minimize window size 
	menuborder		draw menu borders
	name			run xmem under this name
	percent			don't display percentages 
	reverseVideo		reverse video
	synchronous		syncronous mode
	updInterval		interval at which stats are updated
	verbose			verbose mode 
	warnval			display warning pixmap when usage reaches <arg>%
	
13) Troubleshooting

	If you find a problem which is not listed below there are 2 things
	you can do:
		1) Fix it yourself. If this case please send me a short 
		note explaining the problem and the fix. Note that the
		code for xmem is actually pretty simple and for the 
		most part well commented so it should not be hard to
		figure out what's going on. If you can, please do it 
		this way as I am busy enough as is is.
		2) Send me a description of the problem. I'll try to
		attend to it as fast as I can, but work comes first so
		this may take a while. If you mail me about problems be
		sure to tell me *which*version* you are using and which 
		OS you are running under so that I know if the problem has 
		been fixed already and if it is generic or port specific 
		(the help option will list the version number).

	Problem: Compile failes with a problem with the catlist() function
		definition.
	Solution: In terms of portability this is the most fragile part 
		of xmem. I've done my best to make this portable, but there
		may be systems whose compiler simply throws up once he sees 
		catlist. If you do have problems with catlist(), there are a
		number of things you can try:
		1) Try using another compiler (gcc generally accepts the 
		catlist() function as-is). 
		2) Undef __STDC__ in your compiler directives. Most compilers
		do this via the -U flag. 
		If these fail, you'll have to adapt catlist() for your 
		machine. In that case, accept my apologies for the problems
		and please send me a mail telling me what you did so that I 
		can integrate your fix into the sources, sparing others of 
		this misery.

	Problem: Xmem won't find my resource definitions.
	Solution: Xmem handles resources as follows:
		a) xmem checks in the directory pointed at by the environment 
		   variable XAPPLRESDIR. If this doesn't yield any resource 
		   definitions we go to step b. If xmem ignores your personal 
		   resrource definitions, make sure you have XAPPLRESDIR 
		   set to the proper value and exorted. 
	        b) xmem checks the APP_DEFAULTS_DIR. This is defined in your 
		   headers or in xmem.h. If you want to change this you'll 
		   have to recompile xmem.
		The reasoning behind this approach is to allow user preferences 
		to take preference over the system preferences. 

	Problem: The detail window does not resize correctly.
	Solution: This probably means that you are using a non-standard
		font. I didn't program this correctly because I'm not 
		sure how to do it. Try tinkering with the code in
		write_detail() to adjust this to your favorite settings
		or, if you really do fix this, let me know how to do it.

	Problem: xmem seems to start OK but I don't get the window or 
		it displays incorrect values. 
	Solution: Check if your DISPLAY variable is set correctly (you
		can always use the -v falg to see if it does start up 
		correctly).

12) I've found a bug. What now?

	Read section 11 (Troubeshooting) to see if it falls under one of
	the problems listed there. If not, reread the first part of
	section 11 (11.1 and 11.2). Then decide on the best way to approch
	your problem.

13) I've come up with a feature which I think would be useful.

	Here again you can do 2 things:
		1) Implement it yourself. If you do this then
		reread section 5 (What if you change the program?)
		to get an idea what I would like you to do with the
		result.
		2) Mail me. I'll consider it and if I agree with you
		will implement it whenever I find time.

14) I would like to receive future releases of xmem.

	Send me mail telling me that. Somewhere in the mail *list* 
	the email address you want to receive future releases at. 

15) I'm extatic about this wonderful program. How can I make the author happy?

	If you really feel this way, how about a short mail message
	telling me that you are happy about using xmem.

16) I hate this worthless program. It ruins my day.

	Don't use it. Don't mail me!

17) Credits

	The code in get_meminfo() is stolen/adapted from code from 
	the procps package. 
