675 lines
32 KiB
Plaintext
675 lines
32 KiB
Plaintext
<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
|
|
|
|
<book>
|
|
<bookinfo>
|
|
<date>1999-02-08</date>
|
|
<title>LCDproc User's Guide</title>
|
|
<subtitle>Installation and Client Development Guide</subtitle>
|
|
</bookinfo>
|
|
<toc></toc>
|
|
|
|
<chapter>
|
|
<title>Introduction</title>
|
|
<para>LCDproc is a system status monitoring application that drives a
|
|
variety of different LCD-based display devices. It provides a powerful
|
|
framework for networked statistic gathering, adding new monitors or
|
|
LCD-aware applications, and adding new devices.
|
|
</para>
|
|
<para>The client shipped with LCDproc v0.4 can connect to an LCDproc
|
|
server either on the local system or on a remote system as long as it
|
|
is reachable. It extracts the same statistics regardless of where it
|
|
sends this information. The statistics it gathers include CPU
|
|
utilization, memory utilization, disk utilization, network utilization,
|
|
system uptime, time, and date, and so on. It displays this information
|
|
in assorted ways, and can be tailored to taste.
|
|
</para>
|
|
<sect1>
|
|
<title>Supported Hardware</title>
|
|
<para>As shipped, LCDproc v0.4 supports LCD modules from Matrix
|
|
Orbital Corporation, HD447800-controlled LCDs, and can emulate an LCD with
|
|
the curses library or plain, raw, ugly text.
|
|
</para>
|
|
<sect2>
|
|
<title>Matrix Orbital LCD Modules</title>
|
|
<para>
|
|
LCDproc was born out of original tinkering by William Ferrell with
|
|
one of these LCD modules. Their ease of installation and use (as well
|
|
as the amazing amount of patience demonstrated by the folks at
|
|
Matrix Orbital whilst William figured things out) meant one less thing
|
|
to worry about during the early stages of LCDproc's life.
|
|
</para>
|
|
<para>
|
|
These 20x4 alphanumeric modules are connected via standard DB-9 cabling and
|
|
connectors. They draw either 5V or 12V, depending on the module purchased,
|
|
and are attached with a standard floppy cable connector (with a slightly
|
|
modified wire configuration).
|
|
</para>
|
|
<para>
|
|
Once connected, using them is a breeze. They can operate at any number of
|
|
different baud rates and serial configurations, but normally they run at
|
|
19,200 baud, 8-N-1, making them quite quick. Sending ASCII to the module
|
|
will make it simply display that text at its current cursor position. The
|
|
module has a built-in BIOS that recognizes commands (sent by transmitting a
|
|
single-byte "marker" signifying that a command is on the way, followed by
|
|
the single-byte command character itself along with any parameters, if needed)
|
|
allowing the programmer to clear the screen, position the cursor anywhere,
|
|
define custom characters (up to 8 at a time), draw bar graphs and large numbers,
|
|
change the LCD's contrast, and so on.
|
|
</para>
|
|
<para>
|
|
The BIOS included also implements line-wrapping (i.e. writing past the
|
|
twentieth character on the first row will automatically move the cursor
|
|
to the first character on the second row), and screen scrolling (i.e.
|
|
writing past the twentieth character on the fourth row causes the whole
|
|
screen to scroll up one row, clearing the fourth line and positioning the
|
|
cursor at the first character on that line).
|
|
</para>
|
|
<para>
|
|
These modules are fast. Using the auto-line-wrap feature and disabling
|
|
the auto-scrolling feature, the screen can be updated thirty times per
|
|
second if *every* character on the screen is changed. If updating less
|
|
than the whole screen, the LCD can update faster than can be seen by
|
|
the human eye. This, of course, more than meets LCDproc's needs.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>HD44780 Controller-Based LCDs</title>
|
|
<para>
|
|
These LCDs are controlled by the Hitachi HD44780 LCD controller, and
|
|
connect to a system's parallel port. Not much else is known about these
|
|
devices at this time. [Update this section].
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>LCD Emulation</title>
|
|
<para>
|
|
LCDproc can emulate an LCD on a curses terminal (or even on a dumb terminal
|
|
by writing raw text out, if you're that desperate). The output is confined to
|
|
a 20x4 character area, just like on a real LCD, and can be "swallowed" into
|
|
window manager panels such as fvwmbuttons.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1>
|
|
<title>LCDproc Documentation</title>
|
|
<para>
|
|
This document is intended to be full, complete documentation for
|
|
LCDproc. While some information presented in this document is present
|
|
in assorted files scattered across the LCDproc distribution tarball,
|
|
this document is meant to encompass all aspects of dealing with
|
|
LCDproc, from installation, all the way to developing custom clients
|
|
using LCDproc's client/server API.
|
|
</para>
|
|
<para>
|
|
README and INSTALL files will always be distributed with LCDproc, along
|
|
with the requisite copyright and licensing information, but this document
|
|
will eventually replace the content of the README and INSTALL files.
|
|
</para>
|
|
<para>
|
|
This documentation was written in SGML and
|
|
<ULINK URL="http://www.oasis-open.org/docbook/">DocBook</ULINK>. SGML is a
|
|
generalized markup language (of which HTML is a subset), and DocBook is a set of
|
|
layout tools and markups using SGML that lends itself quite nicely to the publishing
|
|
of technical manuals and software documentation like this.
|
|
</para>
|
|
<para>
|
|
In Linux, one can produce DVI, PostScript, HTML, Unix Manual Pages and Info
|
|
pages from the same SGML/DocBook source using
|
|
<ULINK URL="http://www.sgmltools.org/">SGMLtools</ULINK>. Take a look at this set
|
|
of tools if you have any large-scale documentation to write. It might have a bit of
|
|
a steep learning curve, but it's certainly worth the effort.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Installation</title>
|
|
<para>
|
|
This chapter covers the installation process for both LCDproc, and the actual LCD
|
|
module intended for use with LCDproc. Since our experience has involved almost
|
|
exclusively the Matrix Orbital modules, we will spend little time on installation
|
|
instructions for other hardware.
|
|
</para>
|
|
<para>
|
|
If you have successfully installed LCDproc-compatible hardware and would care to
|
|
document how you did so, please e-mail the author of this book
|
|
(choadster@earthlink.net).
|
|
</para>
|
|
<para>
|
|
We will examine the installation process of LCDproc and the hardware it drives in
|
|
small steps, as it is vitally important to pay close attention to detail during
|
|
hardware installation to avoid damaging equipment, as well as during LCDproc's
|
|
installation, since things have become a little more complicated since LCDproc's
|
|
split into a client and server model.
|
|
</para>
|
|
<para>
|
|
First, hardware installation is discussed. If you are not using physical LCD
|
|
hardware to run LCDproc, you can safely skip the hardware installation sections and
|
|
move on to the software installation sections.
|
|
</para>
|
|
<sect1>
|
|
<title>Hardware Installation</title>
|
|
<para>
|
|
Regardless of what specific type of hardware you intend to use with LCDproc,
|
|
installation is usually straightforward, and requires only a few steps. Regardless,
|
|
you must use caution while working inside your computer system or with any hardware
|
|
attachments.
|
|
</para>
|
|
<Warning>
|
|
<Title>Warning!</Title>
|
|
<para>
|
|
Installing new hardware inside a computer system can be dangerous to both
|
|
system components and the installer. Use caution whenever adding a component
|
|
to the inside of your system, altering a power cable, or physically mounting
|
|
a device inside a computer system.
|
|
</para>
|
|
<para>
|
|
When installing hardware inside a computer, make sure it's turned off and that
|
|
its power is disconnected. This is especially important when making changes to
|
|
power cables (as some LCD modules require).
|
|
</para>
|
|
</Warning>
|
|
<sect2>
|
|
<title>Matrix Orbital LCD/VFD Module Installation</title>
|
|
<para>
|
|
The LCD and VFD modules from Matrix Orbital are relatively straightforward
|
|
to install. With a small, regular (flat-head) screwdriver, a spare floppy drive
|
|
power cable, and a bit of luck, installation will take less than an hour.
|
|
</para>
|
|
<para>
|
|
These installation instructions assume that you are installing the module into
|
|
a PC or PC-style system (one with AT- or ATX-compliant power cabling) and that
|
|
you have some idea of where you intend to permanently mount the module. For
|
|
mounting ideas and tips, refer to the section "Mounting" below.
|
|
</para>
|
|
<Tip>
|
|
<Title>Before you start</title>
|
|
<para>
|
|
Your Matrix Orbital LCD or VFD module should be clearly marked with an
|
|
indication of the module's power requirements. It should be either a 5 volt
|
|
or 12 volt unit. You should have this information available before proceeding.
|
|
</para>
|
|
</tip>
|
|
<sect3>
|
|
<title>Power Cable Modification</title>
|
|
<para>
|
|
The first step in installing the module is making the necessary modifications
|
|
to a floppy drive power cable in order to provide power to the module. The
|
|
modifications must be made based on the module's power requirements -- either
|
|
5V or 12V -- depending on which module you purchased.
|
|
</para>
|
|
<para>
|
|
A standard floppy drive power cable has a smaller connection than a "normal"
|
|
PC power connector. However, like a "normal" power connector, it has four
|
|
wires: one yellow, one red, and two black. The red wire provides +5V power, and
|
|
is "hot" or live when the system is powered up. The yellow wire provides +12V
|
|
power, and is also hot when the system is powered up. Both black wires are
|
|
ground.
|
|
[TODO: INCLUDE A FIGURE HERE SHOWING A "STANDARD" FLOPPY CONNECTOR]
|
|
</para>
|
|
<para>
|
|
One of the hot wires and one of the black wires will not be needed for your
|
|
module's power connection; they will be completely removed when the power cable
|
|
modification is complete.
|
|
</para>
|
|
<Warning>
|
|
<title>Warning!</title>
|
|
<para>
|
|
Do NOT make this modification to a power cable attached to a running
|
|
system! Electrocution resulting in personal injury and/or damage to the
|
|
system can result.
|
|
</para>
|
|
</Warning>
|
|
<para>
|
|
Using a regular screwdriver, press down the small metal locking flap of one
|
|
of the two black wires on the small end of the cable, and pull the black wire
|
|
from the connector. Using a pair of needle-nose pliers, squeeze the other end
|
|
of the same black wire, and pull it out of the large end of the cable. This
|
|
black wire can be set aside; it will not be used for the module's power
|
|
connection. Either wire can be safely removed; you may safely remove either
|
|
wire.
|
|
[TODO: INCLUDE A FIGURE HERE SHOWING THIS PROCESS]
|
|
</para>
|
|
<para>
|
|
Next, using the same procedure, remove the unneeded hot wire. If your module
|
|
is 5V, you do not need the yellow (+12V) wire. Conversely, if your module is
|
|
12V, you do not need the red (+5V) wire. The removed wire can be set aside;
|
|
it will not be used for the module's power connection.
|
|
[TODO: INCLUDE A FIGURE HERE]
|
|
</para>
|
|
<para>
|
|
The floppy power connector should now have only two wires attached to it.
|
|
Leave the larger end alone from now on; these connections are correct (the
|
|
larger end connects to your system's power mains). Move the two remaining wires
|
|
to the outside connectors on the small end of the cable. Orientation does not
|
|
particularly matter here; the connector will fit on the module's receptacle
|
|
in either orientation.
|
|
[TODO: A FIGURE HERE]
|
|
</para>
|
|
<para>
|
|
You should now have a properly modified power connector. When physically
|
|
attaching this connector to the module, the black (ground) lead should be
|
|
connected to the pin labelled GND, while the colored (+5V/+12V) lead should
|
|
be connected to the pin labelled +5V/+12V.
|
|
</para>
|
|
<para>
|
|
Test the power connection before connecting the data line or mounting the
|
|
module. Connect the module to the power connector, and the connector to your
|
|
system's power mains. Turn the system on.
|
|
</para>
|
|
<Caution>
|
|
<Title>Caution</Title>
|
|
<para>
|
|
If the module does not immediately display its initial BIOS screen and light
|
|
up its backlight (or light up the screen if a VFD module is being used),
|
|
<EMPHASIS>immediately</EMPHASIS> power down the system, disconnect the module
|
|
and connector, and double-check the modification before trying again. Do NOT
|
|
leave the system on if the module does not immediately respond; module or
|
|
system damage could result.
|
|
</para>
|
|
</Caution>
|
|
<para>
|
|
When the LCD powers up and displays its initial BIOS screen, you've gotten the
|
|
power connection wired properly and can now properly mount the module and make
|
|
its final connections. Matrix Orbital Corporation sells a PC bay insert mount
|
|
for the 20x4 and 20x2 modules (LCDproc, however, only supports the 20x4 at
|
|
present). The inserts provide an easy means of mounting the LCD modules inside
|
|
a PC using one (for the 20x2) or two (for the 20x4) 5 1/4" bays.
|
|
</para>
|
|
<Note>
|
|
<title>Note</title>
|
|
<para>
|
|
Describing how to physically mount the module in a PC case is beyond the
|
|
scope of this document; LCDproc's website contains more detailed mounting
|
|
information and examples.
|
|
</para>
|
|
</Note>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Serial Connection</title>
|
|
<para>
|
|
The LCD module uses a standard DB9 serial connector. You can attach the module
|
|
to your system using a direct cable to the motherboard, or by removing one of
|
|
your system's serial ports from the back of the case, then connecting it to a
|
|
standard serial cable to the module.
|
|
</para>
|
|
<para>
|
|
While connecting the serial cable to the module, be sure to configure the
|
|
module's serial interface settings. Typically, setting the module to its fastest
|
|
setting (19,200 baud, 8-N-1) is recommended. At present, the Matrix Orbital
|
|
module driver in LCDproc is hardwired to use these settings; using different
|
|
ones will require minor changes to the driver's code.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Other Display Types</title>
|
|
<para>
|
|
At present, we do not have any detailed information regarding the installation
|
|
of other types of LCDs. If you have any information that would be useful to
|
|
include here, please contact William Ferrell
|
|
(<ULINK URL="mailto:choadster@earthlink.net">choadster@earthlink.net</ULINK>).
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>LCDproc Distribution Layout</title>
|
|
<para>The current LCDproc distribution contains both the LCDproc server
|
|
and the LCDproc client. It also contains sparse documentation (this
|
|
document will hopefully solve this problem), and a sample Perl client.
|
|
[THIS WILL CHANGE -- REWRITE THIS PARAGRAPH]</para>
|
|
|
|
<sect1>
|
|
<title>Basic Layout</title>
|
|
<para>
|
|
LCDproc is distributed in a single archive containing both the client(s)
|
|
and the server:
|
|
<SimpleList columns=2>
|
|
<Member>clients/</Member>
|
|
<Member>docs/</Member>
|
|
<Member>old/</Member>
|
|
<Member>server/</Member>
|
|
<Member>server/drivers/</Member>
|
|
<Member>shared/</Member>
|
|
<Member>tests/</Member>
|
|
<Member>BUGS</Member>
|
|
<Member>COPYING</Member>
|
|
<Member>INSTALL</Member>
|
|
<Member>Makefile</Member>
|
|
<Member>Makefile.config</Member>
|
|
<Member>README</Member>
|
|
<Member>TODO</Member>
|
|
<Member>WHATSNEW</Member>
|
|
<Member>Contains the LCDproc client and the sample Perl client</Member>
|
|
<Member>Documentation (sparse at the moment)</Member>
|
|
<Member>Contains older source code, unused in compiling v0.4</Member>
|
|
<Member>Contains the LCDproc server</Member>
|
|
<Member>Contains LCDproc's device drivers</Member>
|
|
<Member>Contains shared code</Member>
|
|
<Member>Contains test code not used in compiling</Member>
|
|
<Member>A list of known bugs in the current version</Member>
|
|
<Member>The GNU General Public License</Member>
|
|
<Member>Installation Instructions</Member>
|
|
<Member>File for the "make" utility, used to compile LCDproc</Member>
|
|
<Member>Contains compile-time user-tunable defaults for LCDproc</Member>
|
|
<Member>Read this file first! Contains basic information regarding LCDproc,
|
|
what it does, how it works, and how to start building it.</Member>
|
|
<Member>List of planned changes and improvements.</Member>
|
|
<Member>List of revisions that have been made to LCDproc throughout its
|
|
development. [This should be changed to ChangeLog]</Member>
|
|
</Simplelist>
|
|
</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>A Stroll Through the Code</title>
|
|
<para>
|
|
This section attempts to document how LCDproc works. Both the server and
|
|
the client are explored at the source code level. This section was written
|
|
as an exercise for the author to help him better understand LCDproc's
|
|
inner workings, allowing him to better document LCDproc for end users and
|
|
developers. Feel free to skip past this entire section unless you really
|
|
feel like reading how LCDproc renders screens, manages clients, deals with
|
|
input, and handles trouble.
|
|
</para>
|
|
<sect2>
|
|
<title>The LCDproc Server, LCDd</title>
|
|
<para>
|
|
LCDd is the central component of LCDproc. It is responsible for several
|
|
different activities:
|
|
|
|
<SimpleList>
|
|
<Member>Initializing the output device</Member>
|
|
<Member>Initializing the incoming socket</Member>
|
|
<Member>Listening for client connections and accepting them</Member>
|
|
<Member>Storing screens provided by clients</Member>
|
|
<Member>Storing stats provided by clients</Member>
|
|
<Member>Choose the best screen to display on the LCD based on order of
|
|
client and screen arrival, and by priority</Member>
|
|
<Member>Provide a rich screen-drawing widget set for clients to use</Member>
|
|
<Member>Render screens to the LCD</Member>
|
|
<Member>Gracefully handle dead sockets and clients</Member>
|
|
<Member>Gracefully remove screens and clients when asked to by clients or
|
|
the user</Member>
|
|
</SimpleList>
|
|
</para>
|
|
<para>
|
|
To accomplish all this, LCDd splits into dozens of source files to handle
|
|
different bits of the job. We will examine each of these source files one by
|
|
one (and, to make things easier, in alphabetical order). Header files (*.h)
|
|
will not be included in this discussion.
|
|
</para>
|
|
<sect3>
|
|
<title>server/client_data.c</title>
|
|
<para>
|
|
This file appears to contain code that handles the creation and destruction
|
|
of linked lists for client data.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/client_functions.c</title>
|
|
<para>
|
|
This file actually describes itself as its first comment! It contains
|
|
definitions for all the functions that the clients can run. They are to
|
|
be called only from server/parse.c.
|
|
</para>
|
|
<para>
|
|
Here the functions that clients call when connected to LCDd are actually
|
|
defined and performed.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/clients.c</title>
|
|
<para>
|
|
This file contains code allowing LCDd to handle client connections and
|
|
data structures. It contains functions to initialize the internal list
|
|
of clients, terminate client connections, add new clients to the list,
|
|
add, remove, and retrieve messages to clients' message queues, and
|
|
locating a client's socket.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/input.c</title>
|
|
<para>
|
|
This file contains functions that handle input from keypads, joysticks,
|
|
etc.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/main.c</title>
|
|
<para>
|
|
Where the action is.
|
|
</para>
|
|
<para>
|
|
This file contains LCDd's main() function and supporting code. It begins
|
|
life by configuring signal handlers, then by immediately initializing the
|
|
LCD drivers. (Huh?) It then parses the command line, configuring the
|
|
LCD driver appropriately, then initializes its internal lists and the
|
|
socket.</para>
|
|
<para>
|
|
Next, it forks into a daemon process (shedding its controlling terminal)
|
|
and enters the main loop. The main loop: listens for connections from
|
|
new clients and for input from already connected ones, parses all input
|
|
from connected clients, checks for input, then updates the screen list
|
|
and updates the LCD.
|
|
</para>
|
|
<para>
|
|
Also present are functions to handle graceful exits when various signals
|
|
are received, and a help screen.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/menu.c</title>
|
|
<para>
|
|
This appears to be code to handle server-generated menu screens on the LCD.
|
|
[I don't understand this file in the slightest ... study this harder later]
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/parse.c</title>
|
|
<para>
|
|
This file contains code that parses input from the clients.
|
|
parse_all_client_messages() is called once each time through main()'s loop.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/render.c</title>
|
|
<para>
|
|
This file contains code that actually generates the full screen data to
|
|
send to the LCD. draw_screen() takes a screen definition and a counter as its
|
|
arguments. It builds the screen according to the definition, and using the
|
|
counter as a reference.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/screen.c</title>
|
|
<para>
|
|
This file stores all the screen definition-handling code. Functions here
|
|
provide means to create new screens and destroy existing ones. Screens are
|
|
identified by client and by the client's own identifiers for screens.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/screenlist.c</title>
|
|
<para>
|
|
This appears to be the screenlist handler that decides which screen to
|
|
display based on priorities and screen creation order.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/serverscreens.c</title>
|
|
<para>
|
|
This file contains code to allow the server to generate its own screens.
|
|
Currently, only the server status screen is provided, showing total number
|
|
of connected clients, and the combined total of screens they provide (this
|
|
count does not include the server's screens).
|
|
</para>
|
|
<para>
|
|
It is interesting to note that the server creates a special screen
|
|
definition for its screens, but uses the same widget set made available
|
|
to clients.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/sock.c</title>
|
|
<para>
|
|
This file contains all the sockets code used by the server. This contains
|
|
the code called upon by main() to initialize the listening socket, as well
|
|
as code to deal with sending messages to clients, maintaining connections,
|
|
accepting new connections, closing dead connections (or connections
|
|
associated with dying/exiting clients), etc.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/widget.c</title>
|
|
<para>
|
|
This file houses code that handles the creation and destruction of widget
|
|
objects for the server. These functions are called using the arguments
|
|
passed by the client, then they store the specified widget into a generic
|
|
container that is parsed later by the screen renderer.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>server/drivers/*</title>
|
|
<para>
|
|
These are the individual driver files. Each driver allows LCDproc to display
|
|
its output on a different device. A driver is responsible for accepting
|
|
LCD-like handling instructions from LCDd, and for returning input from the
|
|
device to LCDd.
|
|
</para>
|
|
<para>
|
|
Currently, drivers provided are MtxOrb, hd44780, curses, and joy. The
|
|
joystick (joy) driver doesn't provide output, but only input.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>The LCDproc Client</title>
|
|
<para>
|
|
The client shipped with LCDproc performs all of the statistic gathering
|
|
previously performed by LCDproc v0.3.x. Instead of driving the LCD directly,
|
|
in this version it now connects to LCDd and sends its screens and data there.
|
|
</para>
|
|
<para>
|
|
In this implementation of the statistic-gathering portions of LCDproc, the
|
|
layout departs substantially from the older v0.3.x code. Each screen is
|
|
generated by functions stored in separate files -- one file per screen.
|
|
This keeps files smaller, and code much simpler to maintain and update.
|
|
</para>
|
|
<para>
|
|
The client appears to use files from the share/ tree as well.
|
|
</para>
|
|
<sect3>
|
|
<title>clients/lcdproc/batt.c, chrono.c, cpu.c, disk.c, load.c, mem.c</title>
|
|
<para>
|
|
These files contain the functions implementing all the screens provided by
|
|
LCDproc.
|
|
</para>
|
|
<para>
|
|
Each contains several functions, mostly related to actual statistic gathering.
|
|
They are also apparently responsible for actually transmitting their screen
|
|
definitions to the server and answering the server's requests for statistic
|
|
updates. The functions here do *no* checking to determine if they are being
|
|
asked for. They *do* check to see if they need to create a new screen
|
|
definition or merely update it. It would appear that the client's main() or
|
|
other higher-level function is responsible for calling this function when the
|
|
server asks for an update.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>clients/lcdproc/main.c</title>
|
|
<para>
|
|
This file contains the LCDproc client's main() function, as well as a few
|
|
supporting functions.
|
|
</para>
|
|
<para>
|
|
It first declares and fills a modelist (used only internally by this client)
|
|
that determines which screens will run by default (if the user doesn't
|
|
specify a custom modelist on the command line). The first thing main() itself
|
|
does is configure the signal handlers.
|
|
</para>
|
|
<para>
|
|
Next, it parses the command line for options, yelling at the user if an
|
|
invalid or nonsensical argument has been specified. After it has done this,
|
|
it tries to open a socket connection to LCDd. If successful, execution
|
|
continues. If unsuccessful, the client exits gracefully.
|
|
</para>
|
|
<para>
|
|
Assuming a valid socket connection is established, it sends the "hello"
|
|
command to the server, introducing itself and convincing the server that yes,
|
|
it really *should* serve this client. Next, it calls the mode_init() function
|
|
which appears to set up data structures for the various modes, and then finally
|
|
the main_loop() function which executes indefinitely until the client is
|
|
killed or is asked to stop. Then the program exits cleanly.
|
|
</para>
|
|
<para>
|
|
main_loop() is defined in this file as well. The main loop listens for any
|
|
input from the server, and reacts on what it receives. It appears capable of
|
|
dealing with keypresses, listen/ignore signals, and menu activity. After it
|
|
has reacted appropriately to inputs, it runs the screen asked for by the
|
|
server.
|
|
</para>
|
|
<para>
|
|
The old main() is commented out, but included here for reference. Eventually,
|
|
this will be removed from LCDproc's source. For now, however, it serves as a
|
|
useful reference.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>clients/lcdproc/mode.c</title>
|
|
<para>
|
|
This file contains functions responsible for initializing mode screens and
|
|
calling the appropriate mode screen update function when asked to do so.
|
|
main_loop() passes the server's parsed messages to this function to enable it
|
|
to select which screen is called for.
|
|
</para>
|
|
<para>
|
|
This file also contains reread() and getentry() functions which are used by
|
|
many of the mode screens.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Shared Files</title>
|
|
<para>
|
|
Both LCDd and the LCDproc client make extensive use of linked lists and sockets
|
|
code. Much of that code is shared, and stored in the shared/ tree.
|
|
</para>
|
|
<sect3>
|
|
<title>shared/config.c</title>
|
|
<para>
|
|
This file contains the beginnings of configuration file code.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>shared/LL.c</title>
|
|
<para>
|
|
This file contains all of the functions used in implementing LCDproc's
|
|
linked lists. Functions exist here to create new lists, destroy lists,
|
|
remove an entry from a list, add an entry to a list, move a pointer to
|
|
the beginning or end of a list, move a pointer to the next item in a
|
|
list, the previous item of a list, or to retrieve individual items from
|
|
a list.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>shared/sockets.c</title>
|
|
<para>
|
|
This file contains all the functions used in implementing LCDproc's socket
|
|
handling capabilities. Full bi-directional communication is implemented by
|
|
these functions.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>shared/str.c</title>
|
|
<para>
|
|
This file contains only one function, get_args(). It appears to parse
|
|
command lines (or command line-like strings) for arguments, and returns them
|
|
in a more useful form.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
</book>
|