LOGTIME 1.0	Linux and Windows time logging facility
Copyright (c) 1996 by Christopher S L Heng. All rights reserved.
----------------------------------------------------------------

$Id: readme.txt 1.3 1996/05/09 11:00:40 chris Exp $ /*


CONTENTS
--------

INTRODUCTION
COPYRIGHT
PACKING LIST
INSTALLING FOR WINDOWS
INSTALLING FOR LINUX
CONTACTING THE AUTHOR
MORE INFORMATION


INTRODUCTION
------------

LOGTIME was designed to allow users to keep track of the amount of time
taken and the charges accumulated when logging into an internet service
provider ("ISP"). This might be useful if you use an ISP that charges
you for the time you take when logged onto your account.

LOGTIME has the following features:

- It keeps track of time by being called from your login and logout
script in your dial-up program. It can, of course, be called manually as
well, should your dial-up program not have any means by which you can
execute external programs.

- Some ISPs charge different rates for connections made during the day
and those in the night and/or connections made on a public holiday or
weekend and those on a working day. LOGTIME is able to distinguish
between such connections and display the appropriate results if
configured correctly.

- It displays the amount of time you have spent as well as the charges
you have accumulated so far. If your ISP provides you with a block of
time which you have prepaid, LOGTIME will display the amount of time
that you have left for that month (as compared to the prepaid time) or
the amount of time in excess of the prepaid time that you have used.

- The log file, which contains the record of login/logout times, and the
configuration file are compatible between the versions of LOGTIME for
Windows and Linux. You can keep the log and configuration files in a
place accessible by the LOGTIME for the two systems, and use one set of
files for accesses made in both systems!

- LOGTIME is configurable: you can change the charges it is to calculate
for the time you clock, you can modify the way LOGTIME rounds the time
clocked, you can set the days which it is to consider as public
holidays, or change the times which it is to consider as working hours.

Note that while LOGTIME can give you an idea of the amount of time and
cost you have clocked so far, the results supplied by LOGTIME may not
agree with those calculated by your ISP. Differences can arise as a
result of many reasons: your ISP may start and stop clocking at a
different moment than the moment your script calls LOGTIME , your ISP
may use a different method to round or truncate sessions that take less
than minute, etc.



COPYRIGHT
---------

Copyright (c) 1996 by Christopher S. L. Heng. All rights reserved.

The programs, the accompanying files and documentation are copyrighted (c)
1996 by Christopher S. L. Heng. All rights reserved.

For the purpose of this copyright statement, the programs, their
accompanying files and documentation are collectively referred to as the
"package".

You may use and distribute the programs, their accompanying files and
documentation free of charge only if you agree to all of the following
conditions:

1. All the files that are part of this package must be distributed.

2. The files must not be modified in any way. You may however archive
the files using a different archive format if you like, for example,
using the LZH format or the TAR format.

3. No additional files may be added to the package.

4. THERE IS NO WARRANTY ON THE PROGRAM AND ITS ACCOMPANYING FILES AND
DOCUMENTATION, NOT EVEN THE IMPLIED WARRANTY OF MECHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. YOU AGREE TO BEAR ALL RISKS AND
LIABILITIES ARISING FROM THE USE OF THE PROGRAMS AND THE ACCOMPANYING
FILES AND DOCUMENTATION AND THE INFORMATION PROVIDED BY THE PROGRAMS AND
THE DOCUMENTATION.

5. You may charge a nominal fee to recover the cost of media (such as
for the cost of CDROM or diskettes) and copying when distributing this
package as long as it is clear that you are not charging for the package
itself.

If you cannot accept any of the above conditions, you may not use or
distribute the program and its accompanying files.

If you wish to distribute the package, and are unsure whether your
distribution meets the above conditions, please try contacting me, and
furnish me all the necessary details so that I can let you know.

See also: Contacting the Author



PACKING LIST
------------

The following files are included in the LOGTIME package:

readme.txt	First file you should read
logtime.exe	Windows version of LOGTIME
logtime.hlp	Online manual for the Windows version of LOGTIME
ctl3d.dll	Support file for the Windows version of LOGTIME
logtime		Linux version of logtime (a.out executable)
logtime.1	Manual page for the Linux version of logtime
sample.ini	Sample configuration file with explanations



INSTALLING FOR WINDOWS
----------------------

To install LOGTIME for Windows, simply copy all the LOGTIME files into a
directory on your hard disk. For example, if you wish to place LOGTIME
in the C:\LOGTIME directory of your hard disk, simply create the
directory C:\LOGTIME (you may do this under DOS by typing "MKDIR
\LOGTIME" while you are at the C:\> prompt) and copy all the LOGTIME
files into that directory (you may do this under DOS by typing "COPY *.*
C:\LOGTIME" if your current directory contains the only the LOGTIME
files).

Next you will need to find some way so that LOGTIME is executed each
time you connect to and disconnect from your Internet Service Provider
("ISP"). If you run a winsock package that executes a script file, place
a call to

	logtime -b

in your login script file when there is a successful login; and a call
to

	logtime -e

in your logout script file when your winsock program logs off from the
ISP.

If your winsock package does not execute a script file, you need to
invoke it manually each time you log in and log out. It might be
convenient to associate an item in a Program Manager group with the
command

	logtime -b

and place the text "Begin logging" as the description for that item; and
an item for the command

	logtime -e

and place the text "End logging" for the description for that item.

This way, each time you get a successful connection with your winsock
dialer, just double-click the "Begin logging" icon in your Program
Manager to start the logging; and once you log out, double-click the
"End logging" icon in your Program Manager.

The -b parameter to LOGTIME starts the clock to time the session, and
the -e parameter to LOGTIME stops the stop clock.

If you wish to share the same configuration and data files for both your
Linux and Windows system, install LOGTIME for Windows and its
accompanying files to a directory that is mounted by Linux. In your
Linux SLIP/PPP script, specify that directory using the -D option to the
Linux logtime . For more information about this, see Installing for
Linux. You need to configure LOGTIME before you can use it in any
meaningful way. Run LOGTIME and type F1 and go to the How to Configure
LOGTIME for more details.


INSTALLING FOR LINUX
--------------------

This installation guide assumes that you have managed to get PPP or SLIP
working on your system. I assume that you are using the pppd package
below. If you use SLIP or a different package, adjust accordingly.

At present, the Linux logtime binary requires the a.out shared libraries
to be present on your system for it to work. You will need the a.out
shared libraries 4.5.26 or later for logtime to work. Note that it is
likely that future versions will have both the ELF and a.out binaries.
(It is also likely that future versions will require a later version of
the a.out shared libraries since I hope to upgrade all the development
tools (ie, gcc, libc, etc) on my system.)

To install the Linux logtime binary, simply copy it to /usr/bin or
/usr/local/bin (or any directory in your path that you fancy). Copy the
manual page logtime.1 to your manual directory, such as /usr/man/man1 or
/usr/local/man/man1 (whichever is appropriate for your system). Then add
logtime to the script file that is executed when a ppp or slip link is
established and when the ppp or slip link is disconnected.

For a ppp connection that uses pppd, you might, for example, put the
following line into your ip-up file:

	logtime -D /dos/c/logtime -b

and the following line into your ip-down file:

	logtime -D /dos/c/logtime -e

Note that the logtime for Linux differs from the LOGTIME for Windows in
that the Linux version will search in the LOGTIME directory off the
user's home directory by default for the log data files and the
configuration file unless you specify otherwise. The Windows version
searches for the log data files and configuration file in the directory
from which the LOGTIME executable was executed. The difference is
because most Unix executables (binaries) live in a common directory like
/usr/bin, /usr/local/bin, /bin and the like, whereas Windows executables
often live in their own directory.

You can cause logtime to search for the log and configuration file in a
directory of your choice by specifying that directory in an environment
variable LOGTIMEDIR or by overriding it on the command line with the -D
<data path> option.

For example,

	(LOGTIMEDIR=/dos/d/logtime ; logtime -b)

will cause logtime to search in the directory /dos/d/logtime and use the
configuration file there and save the current time into the log file
located in that directory.

And,

	logtime -D /dos/c/logtime -e

will cause logtime to look into the /dos/c/logtime directory for its
configuration file and clock the end of the session in a log file
located in that directory.

The option -b is used to indicate to logtime the start of a session to
log. The option -e indicates that the user has logged out and that
logtime is to terminate the logging of time for the session.

If you wish to share the same configuration and data files for both your
Linux and Windows system, install LOGTIME for Windows and its
accompanying files to a directory that is mounted by Linux. In your
Linux script, specify that directory to logtime.

Note that the Linux version will also create the data directory if it
does not exist. This applies whether the data directory is the default
directory off the user's home directory or specified via the LOGTIMEDIR
environment or specified on the command line. This is different from the
behaviour of the Windows version.

You will need to configure logtime so that it computes time and charges
according to the rates set by your Internet Service Provider for your
area. To do this create an ASCII text file called logtime.ini in your
logtime data directory (the directory you specify with the -D option or
the LOGTIMEDIR environment variable or the default in your home
directory). WARNING: the text file must be delimited by carriage
return-line feed pairs and not the usual Unix line feed newline
delimiters. This is because the same text file is read by the Windows
LOGTIME.EXE executable. In any case, the Linux logtime also expects the
file to have carriage return-line feed pairs. If you have difficulty
creating such files under Linux, you might want to create the file under
DOS or Windows, or copy the sample.ini file to logtime.ini and change the
values accordingly, or configure using the Windows LOGTIME.EXE
(recommended). The logtime.ini file is formatted according to the usual
formatting rules for Windows 3.1 INI files. The specific variables used
by logtime are explained in the sample.ini file. Please refer to that
file for details if you are not using the Windows LOGTIME.EXE to
configure.

You must configure logtime. Otherwise it will have no idea what rates
your Internet Service Provider uses, what hours constitute peak and
non-peak hours, when the public holidays are, etc.



CONTACTING THE AUTHOR
---------------------

If you wish to contact me about LOGTIME , you may email me on the
Internet via one of the addresses given below (if one of the addresses
fail, try the other). Please note that while I generally would like to
hear from you if you are using the program, and I certainly would like
to know if you discover any bugs in the program, I am under no
obligation to fix any bugs. In fact, I make no promises about even
replying.

My current internet email addresses:
	cyfheng@singnet.com.sg
	ChristopherHeng@pobox.org.sg



MORE INFORMATION
----------------

The complete manual for LOGTIME is available online. To read the manual,
do one of the following:

1. If you are running the Windows version of LOGTIME, start up LOGTIME
for Windows and hit the F1 key.

2. If you are running the Linux version of LOGTIME, you may read the
manual page for logtime using the following command:

	man logtime

Note that the contents of the Windows help file and the Linux manual
page are not identical.

