New file documenting LibGTop internals. Started to document all library

1999-05-28  Martin Baulig  <baulig@Stud.Informatik.Uni-Trier.DE>

	* internals.texi: New file documenting LibGTop internals.
	* reference.texi: Started to document all library functions and
	finished the sysdeps and common references.

5 files changed, 340 insertions, 11 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 1c631e84..b6cb3643 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+1999-05-28  Martin Baulig  <baulig@Stud.Informatik.Uni-Trier.DE>
+
+	* internals.texi: New file documenting LibGTop internals.
+	* reference.texi: Started to document all library functions and
+	finished the sysdeps and common references.
+
 1999-05-16  Martin Baulig  <martin@home-of-linux.org>
 
 	* main.texi: This is now the main file which will @include all
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5d5cebdd..c46457da 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,7 +2,7 @@ info_TEXINFOS		= libgtop.texi
 
 libgtop_TEXINFOS	= libgtop.texi about.texi reference.texi \
 			  auto-macros.texi version.texi main.texi \
-			  white-paper.texi
+			  white-paper.texi internals.texi
 
 EXTRA_DIST		= auto-macros.texi.in
 
diff --git a/doc/internals.texi b/doc/internals.texi
new file mode 100644
index 00000000..4cb9c2d6
--- /dev/null
+++ b/doc/internals.texi
@@ -0,0 +1,107 @@
+@node LibGTop Internals, , Reference Manual, Top
+@chapter LibGTop Internals
+
+@menu
+* General Internals::           General Internals
+* Sysdeps Internals::           Sysdeps Internals
+@end menu
+
+@node General Internals, Sysdeps Internals, LibGTop Internals, LibGTop Internals
+@section General Internals
+
+@menu
+* glibtop::                     The server structure
+@end menu
+
+@node glibtop,  , General Internals, General Internals
+@subsection The server structure - @code{glibtop}
+
+@example
+@cartouche
+typedef struct _glibtop         glibtop;
+
+struct _glibtop
+@{
+        unsigned flags;
+        unsigned method;
+        unsigned error_method;
+#ifdef HAVE_GLIBTOP_MACHINE_H
+        glibtop_machine machine;
+#endif
+        int input [2];
+        int output [2];
+        int socket;
+        int ncpu;
+        unsigned long os_version_code;
+        const char *name;
+        const char *server_command;
+        const char *server_host;
+        const char *server_user;
+        const char *server_rsh;
+        unsigned long features;
+        unsigned long server_port;
+        glibtop_sysdeps sysdeps;
+        glibtop_sysdeps required;
+        glibtop_sysdeps wanted;
+        pid_t pid;
+@};
+@end cartouche
+@end example
+
+@node Sysdeps Internals,  , General Internals, LibGTop Internals
+@section Sysdeps Internals
+
+@menu
+* glibtop_open_s::              Non-privileged initializations
+* glibtop_close_s::             Non-privileged cleanups
+@end menu
+
+@node glibtop_open_s, glibtop_close_s, Sysdeps Internals, Sysdeps Internals
+@subsection glibtop_open_s
+
+This function is used in the non-suid sysdeps library @samp{-lgtop_sysdeps} to
+initialize a server. It should do all initializations that do not need any
+privileges.
+
+@example
+@cartouche
+void
+glibtop_open_s (glibtop *server, const char *program_name,
+		const unsigned long features,
+		const unsigned flags);
+@end cartouche
+@end example
+
+@table @code
+@item server
+Pointer to the @code{glibtop} server structure.
+@item program_name
+Name of the calling program; the implementation will usually
+set @samp{server->name} to this so it'll be used as the program
+name in error messages.
+@end table
+
+Typically, this function will set @code{server->name}, @code{server->ncpu} and
+@code{server->os_version_code} and initialize any of the @code{server->machine}
+fields which do not need any privileges.
+
+It is normally implemented in @file{open.c} in the sysdeps directory.
+
+@node glibtop_close_s,  , glibtop_open_s, Sysdeps Internals
+@subsection glibtop_close_s
+
+This function is used in the non-suid sysdeps library @samp{-lgtop_sysdeps} to
+clean-up a server when it's no longer used.
+
+It must free all resources that were allocated in @code{glibtop_open_s}.
+
+@example
+@cartouche
+void
+glibtop_close_s (glibtop *server);
+@end cartouche
+@end example
+
+It is normally implemented in @file{close.c} in the sysdeps directory, but may
+be empty.
+
diff --git a/doc/main.texi b/doc/main.texi
index c5f777a6..bafe2a45 100644
--- a/doc/main.texi
+++ b/doc/main.texi
@@ -4,13 +4,7 @@
 * About::                       About LibGTop
 * White Paper::                 LibGTop White Paper
 * Reference Manual::            LibGTop Reference Manual
-
-
-
-
-
-
-
+* LibGTop Internals::           LibGTop Internals
 
 
 
@@ -48,6 +42,7 @@ LibGTop Reference Manual
 
 * System Dependent::            System Dependent Functions.
 * Common Functions::            Common Functions.
+* Library Functions::           Library Functions.
 
 System Dependent Functions
 
@@ -73,9 +68,29 @@ Common Functions
 
 * glibtop_mountlist::           Mount List.
 * glibtop_fsusage::             File System Usage.
+
+Library Functions
+
+* glibtop_sysdeps::             
+* Library Parameters::          Library Parameters.
+
+LibGTop Internals
+
+* General Internals::           General Internals
+* Sysdeps Internals::           Sysdeps Internals
+
+General Internals
+
+* glibtop::                     The server structure
+
+Sysdeps Internals
+
+* glibtop_open_s::              Non-privileged initializations
+* glibtop_close_s::             Non-privileged cleanups
 @end menu
 
 @include about.texi
 @include white-paper.texi
 @include reference.texi
+@include internals.texi
 
diff --git a/doc/reference.texi b/doc/reference.texi
index e5975f74..a66c38ee 100644
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -1,9 +1,10 @@
-@node Reference Manual, , White Paper, Top
+@node Reference Manual, LibGTop Internals, White Paper, Top
 @chapter LibGTop Reference Manual
 
 @menu
 * System Dependent::            System Dependent Functions.
 * Common Functions::            Common Functions.
+* Library Functions::           Library Functions.
 @end menu
 
 @node System Dependent, Common Functions, Reference Manual, Reference Manual
@@ -1349,7 +1350,7 @@ We're currently online.
 @end table
 
 @page
-@node Common Functions,  , System Dependent, Reference Manual
+@node Common Functions, Library Functions, System Dependent, Reference Manual
 @section Common Functions
 
 This are functions which a common implementation for all systems; we never
@@ -1362,7 +1363,6 @@ The file system code is taken from GNU Fileutils.
 * glibtop_fsusage::             File System Usage.
 @end menu
 
-@page
 @node glibtop_mountlist, glibtop_fsusage, Common Functions, Common Functions
 @subsection Mount List
 
@@ -1497,3 +1497,204 @@ Free file nodes.
 
 Blocks are usually 512 bytes.
 
+@page
+@node Library Functions,  , Common Functions, Reference Manual
+@section Library Functions
+
+This are general library functions which can be used to get information
+about the library and to control its behavior.
+
+@menu
+* glibtop_sysdeps::             
+* Library Parameters::          Library Parameters.
+@end menu
+
+@node glibtop_sysdeps, Library Parameters, Library Functions, Library Functions
+@subsection Sysdeps
+
+Library function @code{glibtop_get_sysdeps}:
+
+@example
+@cartouche
+void
+glibtop_get_sysdeps_r (glibtop *server, glibtop_sysdeps *buf);
+
+void
+glibtop_get_sysdeps (glibtop_sysdeps *buf);
+@end cartouche
+@end example
+
+Declaration of @code{glibtop_sysdeps} in @file{<glibtop/sysdeps.h>}:
+
+@example
+@cartouche
+typedef struct _glibtop_sysdeps         glibtop_sysdeps;
+
+struct _glibtop_sysdeps
+@{
+    u_int64_t flags,
+        features,
+        pointer_size,
+        cpu,
+        mem,
+        swap,
+        uptime,
+        loadavg,
+        shm_limits,
+        msg_limits,
+        sem_limits,
+        proclist,
+        proc_state,
+        proc_uid,
+        proc_mem,
+        proc_time,
+        proc_signal,
+        proc_kernel,
+        proc_segment,
+        proc_args,
+        proc_map,
+        mountlist,
+        fsusage,
+        netload,
+        ppp;
+@};
+@end cartouche
+@end example
+
+@table @code
+@item features
+This is a bit field (the so-called @dfn{server features}) stating
+for which features we need to use the server.
+@item pointer_size
+This was added in LibGTop 1.1.0 and tells you the number of bits a
+@code{void*} has in the server (this may be different from the
+size on the client machine if we're talking over the daemon to a
+remove machine).
+@end table
+
+The following constants from @file{<glibtop/sysdeps.h>} serve as bit-indices
+for the @code{features} field:
+
+@example
+@cartouche
+#define GLIBTOP_SYSDEPS_CPU             0
+#define GLIBTOP_SYSDEPS_MEM             1
+#define GLIBTOP_SYSDEPS_SWAP            2
+#define GLIBTOP_SYSDEPS_UPTIME          3
+#define GLIBTOP_SYSDEPS_LOADAVG         4
+#define GLIBTOP_SYSDEPS_SHM_LIMITS      5
+#define GLIBTOP_SYSDEPS_MSG_LIMITS      6
+#define GLIBTOP_SYSDEPS_SEM_LIMITS      7
+#define GLIBTOP_SYSDEPS_PROCLIST        8
+#define GLIBTOP_SYSDEPS_PROC_STATE      9
+#define GLIBTOP_SYSDEPS_PROC_UID        10
+#define GLIBTOP_SYSDEPS_PROC_MEM        11
+#define GLIBTOP_SYSDEPS_PROC_TIME       12
+#define GLIBTOP_SYSDEPS_PROC_SIGNAL     13
+#define GLIBTOP_SYSDEPS_PROC_KERNEL     14
+#define GLIBTOP_SYSDEPS_PROC_SEGMENT    15
+#define GLIBTOP_SYSDEPS_PROC_ARGS       16
+#define GLIBTOP_SYSDEPS_PROC_MAP        17
+#define GLIBTOP_SYSDEPS_MOUNTLIST       18
+#define GLIBTOP_SYSDEPS_FSUSAGE         19
+#define GLIBTOP_SYSDEPS_NETLOAD         20
+#define GLIBTOP_SYSDEPS_PPP             21
+@end cartouche
+@end example
+
+@node Library Parameters,  , glibtop_sysdeps, Library Functions
+@subsection Library Parameters
+
+Library function @code{glibtop_get_parameter}:
+
+@example
+@cartouche
+size_t
+glibtop_get_parameter_l (glibtop *server, const unsigned parameter,
+                         void *data_ptr, size_t data_size);
+
+size_t
+glibtop_get_parameter (const unsigned parameter, void *data_ptr,
+                       size_t data_size);
+@end cartouche
+@end example
+
+This function is used to retrieve a library parameter (see below for a more
+detailed description). It returns the size of the retrieved parameter on
+success, zero on failure or minus the actual size of the parameter if
+@code{data_size} was too small.
+
+You may call this function with @code{data_ptr} set to @code{NULL} to get the
+actual size of a parameter (as a negative value).
+
+@table @code
+@item parameter
+The parameter you want to retrieve (see below for constants).
+@item data_ptr
+Pointer to a place where the parameter should be stored.
+@item data_size
+Maximum size of the parameter.
+@end table
+
+Library function @code{glibtop_set_parameter}:
+
+@example
+@cartouche
+void
+glibtop_set_parameter_l (glibtop *server, const unsigned parameter,
+                         const void *data_ptr, size_t data_size);
+
+void
+glibtop_set_parameter (const unsigned parameter, const void *data_ptr,
+                       size_t data_size);
+@end cartouche
+@end example
+
+This function is used to modify a library parameter. Please not that you
+may not set all parameters since some of them are read-only.
+
+@table @code
+@item parameter
+The parameter you want to modify (see below for constants).
+@item data_ptr
+Pointer to the value which should be set.
+@item data_size
+Size of the new value. For fixed-size parameters, this must match
+the exact size of the parameter or you'll get an error.
+@end table
+
+The following parameters are defined in @file{<glibtop/parameter.h>}:
+
+@table @code
+@item GLIBTOP_PARAM_FEATURES
+This is a read-only @code{unsigned long} representing the @code{features}
+field of @code{glibtop_sysdeps}.
+@item GLIBTOP_PARAM_REQUIRED
+This is a @code{glibtop_sysdeps} structure specifying which features the
+client requires the library return. If it fails to get any of them, you'll
+get an error.
+@item GLIBTOP_PARAM_ERROR_METHOD
+This is an @code{unsigned} telling the library what to do if it fails to
+get any of the features that are marked as required via the
+@code{GLIBTOP_PARAM_REQUIRED} parameter (see below for constants).
+@end table
+
+You can use the following constants for @code{GLIBTOP_PARAM_ERROR_METHOD}
+(defined in @file{<glibtop/open.h>}):
+
+@table @code
+@item GLIBTOP_ERROR_METHOD_IGNORE
+Ignore the error condition.
+@item GLIBTOP_ERROR_METHOD_WARN_ONCE
+Warn once about the absense of some of the required features, then modify
+@code{GLIBTOP_PARAM_REQUIRED} so that the missing ones are no longer
+required. This is the prefered value for applications since it'll only
+print out the warning message once and not each time the library tries to
+get one of those features.
+@item GLIBTOP_ERROR_METHOD_WARN
+Warn each time the library fails to get some of the required features.
+@item GLIBTOP_ERROR_METHOD_ABORT
+Abort if the library fails to get some of the required features. This
+should not be used by applications.
+@end table
+