Added "Servers and Daemons" section. Documented the glibtop_init ()

* white-papers.texi: Added "Servers and Daemons" section.
* reference.texi: Documented the glibtop_init () function.

3 files changed, 149 insertions, 5 deletions

diff --git a/doc/main.texi b/doc/main.texi
index bafe2a45..1b17caf7 100644
--- a/doc/main.texi
+++ b/doc/main.texi
@@ -19,6 +19,11 @@
 
 
 
+
+
+
+
+
  --- The Detailed Node Listing ---
 
 About LibGTop
@@ -32,6 +37,7 @@ LibGTop White Paper
 
 * Introduction::                Introduction
 * Overview::                    Overview
+* Servers and Daemons::         Servers and Daemons
 
 Overview
 
@@ -71,7 +77,8 @@ Common Functions
 
 Library Functions
 
-* glibtop_sysdeps::             
+* glibtop_init::                Server Initialization.
+* glibtop_sysdeps::             Server Sysdeps.
 * Library Parameters::          Library Parameters.
 
 LibGTop Internals
diff --git a/doc/reference.texi b/doc/reference.texi
index a66c38ee..4b47aa85 100644
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -1505,12 +1505,103 @@ This are general library functions which can be used to get information
 about the library and to control its behavior.
 
 @menu
-* glibtop_sysdeps::             
+* glibtop_init::                Server Initialization.
+* glibtop_sysdeps::             Server Sysdeps.
 * Library Parameters::          Library Parameters.
 @end menu
 
-@node glibtop_sysdeps, Library Parameters, Library Functions, Library Functions
-@subsection Sysdeps
+@node glibtop_init, glibtop_sysdeps, Library Functions, Library Functions
+@subsection Server Initialization
+
+You do not need to worry about the @code{glibtop *} server structure if
+you don't need - the library exports a @code{glibtop_global_server}
+which you can use everywhere a @code{glibtop *} is expected.
+
+Most of the library and all of the sysdeps function also have an alias
+(which is the function name without the @samp{_l}, @samp{_s} or @samp{_r}
+suffix) which don't take a @code{glibtop *} as argument but uses the
+@code{glibtop_global_server} instead.
+
+@example
+@cartouche
+extern glibtop *glibtop_global_server;
+@end cartouche
+@end example
+
+Library function @code{glibtop_init}:
+
+@example
+@cartouche
+glibtop *
+glibtop_init_r (glibtop **server_ptr, unsigned long features,
+                unsigned flags);
+
+void
+glibtop_init (void);
+@end cartouche
+@end example
+
+This function initializes a LibGTop server. It is automatically called
+when you use any of the LibGTop functions and will use the global server
+in this case.
+
+However, it's appreciated to call @code{glibtop_init} during the
+initialization of your application.
+
+You can for instance use
+
+@example
+glibtop_init ();
+@end example
+
+@noindent
+which is equivalent to
+
+@example
+glibtop_init_r (&glibtop_global_server, 0, 0);
+@end example
+
+Please note that the @code{server_ptr} argument is a pointer to a pointer
+(and thus is of type @code{glibtop **}).
+
+To control what @code{glibtop_init} should actually do, you can use the
+@code{features} and @code{flags} arguments.
+
+The @code{features} argument is a bit-mask (interpreted in the same way
+than @samp{sysdeps.features}) and tells the library which features you're
+interested in. The library will only start the server if this is required
+for any of those features.
+
+You can use the following constants for the @code{flags} parameter to
+control the behavior of the library:
+
+@table @code
+@item GLIBTOP_INIT_NO_INIT
+Tells the library to do nothing. If the value pointed to by the
+@code{server_ptr} argument is @code{NULL}, it will set it to the
+@code{glibtop_global_server} and then return.
+@item GLIBTOP_INIT_NO_OPEN
+Do the initialization, but do not start the server.
+@end table
+
+To modify the way the @code{features} are interpretet, you can use the
+following constants for @code{flags} (as a bit mask):
+
+@table @code
+@item GLIBTOP_FEATURES_NO_SERVER
+Never use the server, always call the sysdeps code directly.
+If you require any privileges to get them and you don't have those
+privileges, the this will obviously not work and the library will
+fail to return some or all of the requested values.
+@item GLIBTOP_FEATURES_EXCEPT
+Inverts the matching of the @code{features} parameter, i.e. if you use
+this flag this means that @code{features} are all the features you are
+@emph{not} interested in.
+Might be useful to say something like "I want everything but ppp".
+@end table
+
+@node glibtop_sysdeps, Library Parameters, glibtop_init, Library Functions
+@subsection Server Sysdeps
 
 Library function @code{glibtop_get_sysdeps}:
 
diff --git a/doc/white-paper.texi b/doc/white-paper.texi
index 8c53c263..f00fcf88 100644
--- a/doc/white-paper.texi
+++ b/doc/white-paper.texi
@@ -4,6 +4,7 @@
 @menu
 * Introduction::                Introduction
 * Overview::                    Overview
+* Servers and Daemons::         Servers and Daemons
 @end menu
 
 @node Introduction, Overview, White Paper, White Paper
@@ -47,7 +48,7 @@ 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.
 
-@node Overview,  , Introduction, White Paper
+@node Overview, Servers and Daemons, Introduction, White Paper
 @section Overview
 
 This section should give you a short overview on how LibGTop was developed, which
@@ -88,3 +89,48 @@ only contains the @dfn{features} which need privileges.
 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.
+
+@node Servers and Daemons,  , Overview, White Paper
+@section Servers and Daemons
+
+LibGTop gives you the possibility to use different LibGTop "servers" and
+"daemons" in your application.
+
+Normally you do not need to worry about this things since LibGTop auto-
+matically opens a pipe to its server it it's required, but this can also
+be customized to fit your needs.
+
+For instance if you have a small applet which is only interested in disk
+usage there's no need to fork a separate server process since you don't
+need any privileges to get them on any of the supported systems. This can
+be archieved with a special call to @code{glibtop_init_r} on startup.
+
+There's also an option to tell @code{glibtop_init_r} that you're only
+interested in several features - for instance cpu and memory usage. In
+this case LibGTop will only fork a server process if it's required to get
+cpu and memory.
+
+You can also tell @code{glibtop_init_r} to start the server only on demand,
+this might become useful in command-line based programs. For graphical
+applications it's normally best to start the server directly during their
+initialization. The same applies for any time critical applications (since
+@code{fork} is an expensive operation on some systems this may lead to
+incorrect statistics).
+
+LibGTop also allows you to talk to a remote machine using the
+@dfn{LibGTop daemon}. This daemon is based on @code{gnuserv} from
+GNU Emacs and should be run as an unprivileged user. It has support
+for either @code{xauth} or host based authorization.
+
+This daemon itself behaves like a LibGTop client application, i.e. it
+forks a server process if this is required.
+
+The main use for this daemon is when you want to monitor a machine which
+is either very slow or has very low disk space. In this case you don't need
+to install the whole client application (for instance GTop) on the remote
+machine but only a very small (maybe also statically linked) executable and
+run the graphical application on a more powerful machine.
+
+It can also be used to monitor a remote machine over a very slow link such
+as a dialup connection since the conversation between LibGTop client and
+daemon uses much less bandwith than an ordinary X11 connection.