

	        pppcosts / ppptime  Version 0.66

 	        Control your online time / costs

	     Copyright (c) 1996,7 Tillmann Steinbrecher
			 tst@bigfoot.com




First of all, make sure you've got the latest, up-to-date information.

	    visit http://www.isjm.com/tst
     
          for the latest pppcosts info and download links.





1. WHAT IS PPPCOST?
          
pppcosts is a small utility that calculates and displays the time
(and phone costs) you have been online using a modem or ISDN ppp
connection. The time and costs are saved, so that you can use
pppcosts to keep track of your monthly phone costs. Cost files for
many phone companies are included. If your phone company isn't
on the list, then you can create a costfile on your own, which
is very easy.

pppcosts uses hardly any system resources; CPU load and memory
usage is neglectable!

If you don't need information about phone costs, a utility called
ppptime is also included in the package that just displays the
online time.

pppcosts now also comes with a X interface written in Tcl/Tk.
See README.X for details.

See the TELECOMS file for a list of supported phone companies.
If your phone company isn't on the list, then you can create
a costfile on your own, which is very easy. See the section about
custom-made costfiles.

2. BINARY DISTRIBUTION

If you have the binary distribution, then "cd /" and untar the archive.
Go to /usr/local/pppcosts and change the link costs.so to your telelcom.

3. HOW DOES IT WORK?

It's easy :)
You start by building your pppcosts executable.

If you have ISDN uncomment the line "#ISDN=-DISDN" in the
Makefile.config by removing the "#".

If you have FreeBSD the uncomment the line "#OS=-DFREEBSD" in
the Makefile.config.

Look at the TELECOMS files to see the list of supported phone
companies. If yours is not included then you can easily create
a costs file for yours. See "MAKING YOUR OWN COSTFILE" below.

There are three options to choose the phone company you want.

a) You edit the entry DEFAULT in Makefile.config and
   replace it by the phone company of your choice
b) You have everything installed and change the link
   costs.so to the company of your choice by doing:
   
       cd /usr/local/lib/pppcosts
       ln -s -f your-choice-costs.so costs.so
   
   This way you can easily change between different phone
   companies
c) You go to the install directory and remove all *.so
   objects you don't need and move your phone-company.so
   file to costs.so
   
After compiling you will then find a "pppcosts" executable.
Be aware that you probably need root privileges if you don't
change the INSTDIR install directory in Makefile.config to
compile and install pppcosts.
After installation simply run pppcosts, and it will watch
for ppp activity and save the online time and costs in the
file ~/.pppcosts.
The "ppptime" utility will also be built (but not installed);
you can use it just like pppcosts, but it won't display the
costs, only the online time.

If you use X, then you can use the scripts "pppc" or
"pppt" which run these programs in cute little xterms.

4. ADVANCED FEATURES

- beeping option:

pppcosts can beep ten seconds before a new unit starts,
to let you "max out" unit usage and hang up in time
before a new unit starts.
For the internet maniacs: pppcosts also lets you set
a maximum cost per session. If this cost is exceeded,
then it will become very annoying by beeping once
per second. A maximum total cost can also be set.
Beeping can be enabled by editing the makefile.
Simply edit it, it's self-explanatory.

- syslog option:

pppcosts can run as a background task, writing its
output to syslog (normally /var/log/messages).
By default, it will log every 300 seconds.
Usage: 'pppcosts -l'

- log time / delay time option:

you can specify the time interval in which pppcosts
checks whether you're online. Default is one second,
or 300 seconds when using the syslog option.
The higher the time specified, the less accurate are
the time/cost values.
Usage: 'pppcosts -t <time>'
Example: 'pppcosts -t 5' to log every 5 seconds

- specify a file other that ~/.pppcosts to save cost/time:

If you want pppcosts to use a different file to save the costs
then ~/.pppcosts, you can specify it with the '-f' switch.
Example: 'pppcosts -f /var/log/global-costs'.

- signal handling

Normally, pppcosts doesn't record the current costs when
it's killed. If you don't like this behavior, simply use
the signal handling option 'pppcosts -s' to change it.
This way, pppcosts will write the current costs down to
the cost file when you terminate it.
Note: If you use this option, terminating and restarting
pppcosts while the ppp link is active will cause the program
to record the costs for the current connection multiple times,
so make sure you don't restart pppcosts while you're online
when using the -s option.

- detection of online time if pppcosts is started long after
  the ppp link came up:

Although ppptime/pppcosts is most useful if you run it all the
time, you can still calculate the costs for you current online
session even if the program was *not* running when you started
your online session.
Example: You have been online for several hours.
If you start pppcosts/ppptime now, it will figure out for
how long you have already been online before pppcosts/ppptime
was started. pppcosts can even calculate the costs for your
call; this works even if you've been online for several days
without interruption ;-).
NOTE: This will not work for the ISDN version or for the
per-minute pricing scheme version. These versions have to
be running at the time the ppp link becomes active.

- newline option

This option is mainly for use with the X interface. Use 
'pppcosts -n' to cause pppcosts to send a "\n" after every
line it displays.

- no usage of device files

The modem version of pppcosts does *not* use any of the device
files in /dev/. The ISDN version uses /dev/isdninfo.
You don't have to be root in order to run the program in both
cases.

- no title option:

if you want pppcosts -not- to print the title then just
start it with the -T switch

5. CUSTOMIZING PPPCOSTS

You can customize pppcosts by editing pppcosts.h

- the beeping option (enabled in makefile)

'beep_before' in pppcosts.h indicates how many seconds before
a new unit starts pppcosts should beep. Default is 10 seconds.

'maxsession' sets the maximum number of units for a single
session. If this number is exceeded, pppcosts will warn
you that you've been online for too long by beeping
annoyingly.

'maxtotal' sets the total maximum number of units (since the 
last creation of ~/.pppcosts, e.g. within one month).
If this number of units is exceeded, pppcosts will beep
continuously.

- the DIAL_TIME option for more accurate online
  time measurement (remove the /* */ to enable)

The online time reported by pppcosts used to be a little
inaccurate because the time the modem took to dial
was counted as online time. Now, you can set a number
of seconds to subtract from the online time.
Example: Your modem takes 8 seconds to dial. Then you
must use '#define DIAL_TIME 8'.
*WARNING*: With some ppp configurations, the online time
reported by pppcosts is the time since the ppp link
became active. In this case, dial time is not counted
as online time. Therefore, the time reported by pppcosts
is shorter than the actual online time.
To fix this, set DIAL_TIME to a negative value. In this
case, DIAL_TIME should be the time the modem handshake
and the login take. Example: Modem handshake & login
take 15 seconds. Use '#define DIAL_TIME (-15)'.

- the TELL_CONNECTION_TERMINATED option

When defined, this option will cause pppcosts to display
"Connection terminated." whenever the ppp link is terminated.
Enable it if you like this display. Not recommended if you're
using a three-line xterm to run pppcosts, but looks better
if you're using a four-line xterm (e.g. captured in a
FVMWButtons bar).

- the ISOLOG option

Settting ISOLOG means that logs are written in following format:

         1999-03-23 19:56:18 00:17:16  $0.30  (01:15:46  $1.80)
         (date, end time, call duration, cost, total time, total cost)

This uses the ISO 8601 date format described at
http://www.cl.cam.ac.uk/~mgk25/iso-time.html. Otherwise the logs will 
be written in a more verbose style:

         Tue, 23 Mar 1999  19:39:02 - 19:56:18  00:17:16 $0.30  (01:15:46 $1.80) 

- other options

can be set in pppcosts.c by people who are interested.
You can customize, modify & improve pppcosts according
to your needs :-)

6. MAKING YOUR OWN COSTFILE

There is no costfile for your phone company? No problem:
create your own costfile - this is highly encouraged!

Even if you're not very familiar with C programming, don't
be afraid to mess with the source. It won't bite, and I've tried to
make it real easy to create your own cost tables. 

If you create such a file, let the others share it - if you
send me your file, I will include it in the next official release.

Thanks in advance. Ok, here's how to proceed:

(Experienced C programmers: skip this. The code is obvious!)

Take an existing costfile. You can take a simple costfile like "pt-costs.c"
to start with.
If you want to create a more sophisticated costfile, which will
respect public holidays, for example, you may want to take de-costs.c
as a basis for your own file. But probably take the file that describes
the cost scheme most similar to the one of your phone company.

Copy the file you have selected to a new name, e.g. "us.att-costs.c".

Now you can modify it according to your phone company's prices.
This is really easy, just look at the existing examples. You can set a
few variables that define the behaveour :

- DECIMALS defines how many digits the price should have. Set
  'char DECIMALS='2'' to cause pppcosts to display 2 decimals. Sometimes
  this is undesired, e.g. with the Yen. If you modify this line to
  'char DECIMALS='0' ', then the line "...0 Yen" will be displayed
  instead of "..0.00 Yen".

- CURRENCY_AFTER_COST defines whether the currency should be displayed
  before or after the price. Set 'char CURRENCY_AFTER_COST=1', if in
  your country the currency comes after the price. Example: You live
  in France. By default, pppcosts would display "... FF 0.00". If you
  add the above line, pppcosts will display "... 0.00 FF" instead.

- CURRENCY and COSTS_PER_UNIT are should be pretty self-explanatory,
  I guess ;-)

- If your phone company charges per minute and alters the price per
  minute at different times of the day then PRICE_PER_MIN should equal 1.
  One effect of this is that .pppcosts stores the total cost rather
  than total units, so be careful when changing the default costs type.

- INITIAL_COST defines the cost of a connect. If your company charges you
  10 cents when you get through then set 'float INITIAL_COST=0.1'.

- MIN_COST is the minimum your telephone company will charge you for a call.
  You don't have to set MIN_COST, but in case you do, be aware that is has
  to be equal or greater than INITIAL_COST (MIN_COST >= INITIAL_COST !) since
  the INITIAL_COST is allways included in the MIN_COST.
  
Finally, adapt the unit lengths (in seconds) and the times in the costfile
by modifying the "if" statements.

To use your newly created costfile, list it in the src/telecom/Makefile
and run make. Link it to costs.so. Then test your pppcosts version, and
send it to tst@bigfoot.com. That's it.

If you're too lazy, simply use ppptime. You won't get any
cost display then.


7. HOW DO I RESET THE PHONE COSTS / TIME ?

Ok. You just got your phone bill. If you survived the shock ;-),
you'll want to start calculating the costs for the next month.
Simply delete the file ~/.pppcosts. The next time you will go
online, it will be recreated.
Works the same way for ppptime, except that the file is
called ~/.ppptime.
If you're using the '-f' option, you must of course delete
the specified file.

NOTE: As the time/cost file is located in the home dir of
each user, the costs will be calculated seperately for each user.
If you don't like this, use the '-f' switch to select a
global costfile.

8. I WANT X!

Well, this is why pppcosts comes with a neat X interface
written in Tcl/Tk.
If you're worried about the memory requirements of
the Tcl/Tk interface, or if you don't have Tcl/Tk on
your system, then there's another solution:

There are two shell skripts that run the programs
in an xterm using a special geometry.

These scripts are called "pppt" and "pppc". Figure out yourself
which script runs pppcosts and which one runs ppptime ;-).

Why don't you let this window sit on your X desktop so
that you can always watch your phone costs.
It's a goot idea to remove the border of these windows
by adding a line like
	Style  "pppcosts"       NoTitle, Sticky
in the case of FVWM.

Another X window program that performs a similar function
is called "momon". 
Momon can also calculate costs for bbs calls using Seyon, 
minicom or any other program. Unlike pppcosts/ppptime, it
uses /dev files.
Momon is a really nice program; however, it uses quite a
lot of system resources. My momon executable is over 700K
large.
Why don't you just download momon from the author's homepage
http://www.uni-karlsruhe.de/~Klaus.Luft and have a look at it.

Another program that does about the same thing as
pppcosts and has an X interface is called tcharge.
You can get it from:
ftp://theo.physik.uni-bremen.de/pub/linux/collected/ppp/
Tcharge doesn't have all the options of pppcosts,
but it also comes with many costfiles, derived from
the pppcosts costfiles.


9. COSTS FOR CALLING A BBS

The modem version of pppcosts doesn't work when you go online
by calling a BBS. It only watches for PPP activity.
If you absolutely need this feature, get momon (see 6.
above). There is also a modem monitor daemon ('momond')
which I think can do this. 

The ISDN version will work if you call a BBS, as it
watches the ISDN device and not the ppp daemon.

10. NEW FEATURES

See CHANGELOG.

See the 'credits' part below to find out who contributed
what.
For a complete revision history, see the pppcosts web page:
http://www.isjm.com/tst

11. THANKS & CREDITS

pppcost really is the work of its contributors.
My thanks to everyone who has contributed source or ideas
(in no particular order):

??? <root@excalibur.tu-graz.ac.at>
	- Provided costfile for Oesterreichische Telekom at-costs.c

Aky <aky@mail.nevtron.si>
	- Provided costfile for Slovene Telekom sit-costs.c	

Andrew Victor <avictor@itu1.sun.ac.za>
	- provided South African costfile

Anthony Dien Yiu Cheng <a.d.y.cheng@damtp.cam.ac.uk>
	- Provided costfile for Cambridge cambridge-costs.c

Antonio Coutinho <ajc@di.uminho.pt>
	- Provided costfile for Portugal Telecom pt-costs.c

BaLi of IBMPC <tothbali@lisa.njzki.hu>
	- Provided costfile for Hungarian MATAV matav-costs.c

Carsten Schwede <teddy@frankfurt.netsurf.de>
	- Wrote X interface. See README.X for details.

Christoph Holz <Christoph.Holz@inka.de
	- removed bug in calculation of times
	    
Dennis McMurchy <denismcm@gol.com>
	- Provided costfile for Japanese NTT ntt-costs.c

David Segonds <david@teaser.fr>
	- Provided costfile for France Telecom fr-costs.c.
	
Davor Perkovac <perkovac@fly.cc.fer.hr>
	- Provided costsfile for Croatian PTT Internet Services
	  hr.hpt.internet-costs.c - this is maybe allready integrated
	  in hr.hpt? If somebody has a clue please tell me.

Didier Chalm <didier.chalm@infini.fr>
	- Provided french costfile ft-costs.c, which is the
	  best & most sophisticated costfile. Had the idea for
	  the 'next in xx:yy' display and has sent source for this.
	  Beta-tested several releases.

Gasper Fele <gasper.fele@guest.arnes.si>
	- Provided costfile for Slovene Telecom si-costs.c.
	
Goran Koruga <goran.koruga@snet.fer.uni-lj.si>
       -  Had the idea for the syslog feature & implemented it.
	  Added -t option. Wrote new command line handler.
	  Fixed bug in sit-costs.c.
	  Implemented signal handling (-s option).

Jean-Marc Wislez <jmwislez@charlie.luc.ac.be>
	- Provided costfile for Belgium be-costs.c

Joachim Tandler <tandlerj@cips01.physik.uni-bonn.de>
	- Had idea for '-f' switch, sent source for it.

Juan Cirer <jcirer@arrakis.es>
	- Provided Spanish costfile. Others have
          sent Spanish costfiles, too. Thanks to all of you!

Karl <mini@stud.uni-sb.de>
	- Provided German Regio50 tarif, now in dt-costs.c

Klaus Herrmann <kherrman@aix550.informatik.uni-leipzig.de>
       -  Provided a new dt-costs.c file that takes into
	  account public holidays (using a sort of "perpetual
	  calender").

Lee Maguire <lee@wetware.demon.co.uk>
	- Revamped the code to make it more structured,
	  added comments, added code for per minute price
	  structures, found bugs in beta release & fixed them,
	  and gave me a few good ideas, provided bt-costs.c
	  for British Telecom. Has contributed a version of
	  pppcosts that would display its output as the X
	  root cursor - unfortunately this patch has not made
	  it into the official release due to lack of time.

Luc Jannsen <ljannsen@pi.net>
	- Patch for initial cost of a connection, costfile for
	  PTTelecom Netherlands nl-costs.c.

Luis Mara Cruz <luismc@failure.ddns.org> and Martin Hoeppner <hoeppner@cww.de>
	- Patches for loging to file. Both approaches were integrated
	  and then included into pppcosts.
	  
Marco Catinelli <cat@lt.flashnet.it>
	- provided Italian costfile it-costs.c

Markus Gutschke <gutschk@uni-muenster.de>
       -  Author of isdnbutton (where I got a part of the code
	  for the ISDN version of pppcosts from).

Matthias Kabel <matthias.kabel@salzburg.co.at>
	- Provided new costfile for Austrian Telecom at-costs.c.
	
Pedro Abreu <paab@camoes.rnl.ist.utl.pt>
	- Provided new costfile for Portugal Telecom pt-costs.c.
	
Peter Lacus <bedo@bedo.sk>
	- costfile for Slovakia
	
pppcosts Rudolf Kompf <kompf@i e-le.de>
        - contributed a patch to the syslog option, which also
	  didn't make it into the official release due to lack
	  of time.

Ragnar Hojland Espinosa <tech.support@redestb.es>
       -  Brought good ideas, found bugs in beta release & fixed
	  them. Has also sent a Spanish costfile. Implemented
	  MIN_UNITS_PER_CALL.

Reinout <reinout@toaster.dark4ce.com>
	- provided Dutch costfile nl-costs.c

Rui M. Silva <rms@ssi.aaum.pt>
	- updated costsfile for Portugal

Roland Egli <egli@swissonline.ch>
        - Provided Swiss costfile ch-costs.c. Others have
	  sent swiss costfiles, too. Thanks to all of you!

Stephane Legrand <root@sequoia.lituus.fr>
	- FreeBSD compatibility fixes.
	
Timo Engelke <time.engelke@frankfurt.netsurf.de>
	- The author of a similar free utility for Windows NT/95,
	  and he gave me the idea to write pppcosts. He has also
	  sent source code, which I never looked at.

Thorsten Lyng Johansen <tljo93@kom.auc.dk>
	- Provided costfile for TeleDanmarK.

Tomas Pospisek <tpo@spin.ch>
	- Various bugfixes, cleanup, dynamical linking with
	  differnet costfiles, beep configurable, reorganisation
	  of package, integration of contributed patches,
	  costfile for Sunrise ch.sunrise-costs.c.
	  maintaining pppcosts since 0.06
  
Toni Bilic <tbilic@efos.hr> and Dimitrios P. Bouras <dbouras@hol.gr>
	- Provided costsfiles for Croatian Academic and Research Network
	  hr.carnet-costs.c and for Croatian PTT hr.hpt-costs.c.
	  Dimitros has created the way cool XISP package. Check it out.
	  
Volker Boerchers <boercher@physik.uni-bremen.de>
	- Author of tcharge. Has found minor bugs in some
	  costfiles while converting them to tcharge format
	  and informed me about these so that I can fix them.

Erwin Waterlander <waterlan@xs4all.nl>
	- costfiles for Netherlands' KPN

Witold Kulinski <wkulin@ikp.atm.com.pl>
       -  Provided costfile for Poland, found bugs in beta
	  release.

Wojtek Bojdol <wojboj@lp.net.pl>
       - new costfile for Poland

You <you@yourdomain.com>
	- Please provide the costfile for your company !

Did I forget anybody? Please complain...

12. TO DO

- Whatever you suggest or implement!

- ppptime development is being discontinued due to lack of
  interest. I haven't received any feedback about ppptime.

- Maybe check out Dimitrios P. Bouras' XISP package and make
  pppcosts use the same config files for the telecom data.
  XISP's got an excellent editor for that. This way XISP could
  profit from contributed pppcosts-costs files and vice-versa.
  
13. LICENSE / CONTACTING THE AUTHOR

pppcosts/ppptime are freeware programs. They are distri-
buted with complete source under GNU GPL, version 2.

Well, you don't need to pay, but why don't you send me
an email to encourage further development, if you find
this program useful (or not)?

*** And, of course, on April 18, you should follow the
program's instructions ;-) !

Anyway, if you want to send bug reports, costfiles, patches,
or if you'd like to participate in beta testing of new
releases:

Contact tst@bigfoot.com.

Check out http://www.isjm.com/tst
for info & updates.
