Tcharge

Tcharge is a tool to watch the time a telephone connection is up and the money to pay for it. It works both for `per unit billing' and for `per second billing'.
On Invocation tcharge pops up a window containing an analog clock and an additional text field. The clock indicates the time elapsed since the start of the program, while the text part of the window gives information about the phone units and/or the charge spent so far.
Alternatively, tcharge can work without any visual output at all, quiet writing computed charges to files in the background.

Overview

Supported Countries
Options
Summary Information
Tools
Tcharge and PPP
Tcharge and ISDN
Files
Support
Charge Modules
Bugs
Author

Tcharge may either work in the daemon mode or in a normal mode:

Tcharge can warn you some seconds before a new unit begins with a little alarm like flashing the window or with a bell.
When compiled with `-DREMINDER' tcharge can warn at regular intervals of having spent a certain amount of money, units or minutes by popping up a message window.

Tcharge catches signals SIGHUP, SIGINT, SIGQUIT, SIGPIPE and SIGTERM to print a connection statistic to a file or to syslog before exiting (see option `-file') and to remove the tcharge PID-file before exiting.

When compiled with `-DPRINT_CHARGE_STRUCTURE' an extended help option -help-charge is available which prints a nice table of the charge structure as given in the header file `charge.h' Very useful to check the correct charging, especially when testing new TC definitions!

Most of the source concerning X is derived from rclock written by Rob Nation. Since Tcharge is a derivate of rclock it also conserves memory by not using the X toolkit or any widget set.

Supported Countries

The phone companies of the following countries are supported so far:
Germany, France, Japan, Portugal, Slovenia, Hungary, Belgium, Swiss, Italy, Netherlands, South Africa, Spain, Danmark and the UK.

If you want tcharge to take into account e.g. some special discount schemes or your provider charges, this is possible to realize - and very easy for you even without any programming knowledge.

Options

The options supported by tcharge are listed below. If you prefer the GNU-style long options, you may two hyphens instead of one.

• -help
  Print a help message with tcharge options.
• -version
  Print tcharge version and the name and date of the charge definitions. Use this option for a first check of the charge definitions.
• -help-charge
  Prints a nice table of the charge structure as given in the header file `charge.h' Very useful to check the correct charging. (Use this first!)
• -geometry window-geometry
  Create the window with the specified X window geometry.
• -bg color
  Use the specified color as the window's background color.
• -fg color
  Use the specified colour as the window's foreground color.
• -font font_name
  Specifies a font other than fixed to use for both, main and message window.
• -update n
  Update clock face and telephone units every n seconds (default: 15 seconds). If the update rate is 1 second, a second hand will be displayed.
  In daemon mode tcharge will look for the file to watch every n seconds but switches to n=1 immediately when the file is present (in order not to miss the end of the connection). Since the start of the connection is determined by examining the creation time of the file to watch there is no need to choose a unnecessary small update value.
• -zone n
  Choose the regional zone for the call. The zone number n defaults to zero, usually for local area calls. If it is a long distance call you have to choose higher values depending on your telephone company (Germany: 0 to 3). Try option -help to get more info.
• -holiday
  "Today is a public holiday: use weekend charging."
  Tcharge keeps a list of public holidays for your country. If this list is empty or incomplete (find out with option -help-charge) you may easily complete the source file for your country instead of using this option (see section Charge Modules).
• -before n
  Assume connection started n seconds before tcharge started.
• -after n
  Assume connection ends n seconds after termination of tcharge.
• -noclock
  Do not draw a clock - only print the units/charges spent so far.
• -noX
  No X-Window-support at all: don't draw a clock or a textfield - only write connection statistics to the logfile or to syslog (use it with option -file).
• -units-only
  Print spent units (not the charge). Not available when `billing per second' since `unit's are not calculated, but default when `billing per unit'.
• -charge-only
  Print charge (not the units). Default when `billing per second'.
• -units-and-charge
  print both, spent units and charge. Not available when `billing per second'.
• -warn-seconds sec
  Set off a little alarm sec seconds before the next unit begins (see option -bell for the meaning of this "little alarm"). Tcharge ensures that this alarm will not come too late because of a large -update value! (But for that reason the alarm may come clockupdate seconds to early ;-)
  This option is not available when `billing per second' since `unit's are not calculated.
• -bell
  Change the meaning of "little alarm" into a simple beep. (Default is a short flashing of the screen e.g. switch to reverse video for a short time and switch back.)
  A little alarm is set of in two cases:
  In case of billing per unit when the option `-warn-seconds' is given .
  In case of billing per second when getting online and on disconnect.
• -warn x<curr_name> | Nunits | Nmin
  Warn at regular intervals of having spent a certain amount of money, units or minutes. `N' is an integer while `x' is a `float' charge value. If the "name" of your currency (<curr_name>) is an abbreviation and contains a dot, don't let it out, e.g. "800L." instead of "800L"!
  Everytime e.g. the number of units is equal to or greater than N, 2N, 3N,... a message window will be popped up in the center of the screen. When the user clicks a mouse button on the window, it will be popped down. (Do not use the `kill' button since this would kill tcharge also!)
  Note: When the -update value is large, warnings will often come lately!
• -file logfile
  Append connection statistics to the file `logfile' when the connection is terminated or tcharge exits.
  Importand for "normal mode":
  The charges will be written on exit of tcharge. Since Tcharge will not terminate itself, you must kill it with an explicite kill command. Don't kill with signal 9 (SIGKILL) since this would not allow tcharge to do anything than instantly die. Use signal SIGTERM instead (kill -15 ... or simply kill ...). Instead of kill you may use the command killall tcharge. This will terminate all open tcharge processes.
• -syslog
  You may also go the official way and let tcharge log the charge information via the system logging mechanism syslog. Usually the messages then will go to the file message (see file /etc/syslog.conf for the location of it, e.g. /var/log/.
• -user[=<username>]
  When writing a connection summary (options -file or -syslog) include the user name. Use this option if you have more than one user having modem-access and if you want to make charge statistics `per user'.
  Normally, it's an easy task for a program to find out the name of the user who invoked it; that's why setting the name explicitely (via "=<username>") is only optional. But if tcharge is started by some e.g. initialization script of pppd (ip-up), then the user name found by tcharge may be "root" or "ppp" instead of the real user name. (If there is a difference between the login and the effective user ID, tcharge will print both names.)
• -watch-file watch_file
  This option switches to daemon mode, since tcharge does not start charge computing as long as watch_file does exist and you do not have to terminate tcharge to end charge computing.
  For PPP take the name of the PID-file of the pppd daemon (usually /var/run/ppp0.pid). This you may have tcharge in the backround while an entire X session.
  This option is not available if tcharge is compiled with the `-DISDN' flag!
• -start seconds
  Set the start time of the call. seconds must be given in `time_t' (Standard Unix/C: seconds since 1.1. 1970). Read Doc/README.batch on how to use tcharge for batch jobs (in connection with option -end). Use the included script date2second (see section Tools) to generate time_t values from date/time.
• -end seconds
  Set the end time of the call. seconds must be given in `time_t' (see option -start).
  If this option is given, tcharge will not open a X-Window and exit after computing the charge only once, so you might use tcharge for batch jobs.
• -isdn
  This option replaces the -watch-file option for ISDN users. Tcharge checks `/dev/isdninfo' for ISDN-connections.
  This option implies -update 1!
• -pidfile
  Change location and/or name of the tcharge PID-file. Normally, the PID file of tcharge is /var/run/tcharge.pid. If you don't have write permissions for this directory, you can use this option.
  If you choose the special file name "false", no PID-file will be written.

Summary Information

The Format of the summary information you get with the -file option (without option -user) is like this:

01/24/1997 Connection [Fri, 14:55:27] -> [Fri, 14:56:33]
01/24/1997   duration: 00:01:07, units: 1, charge: 0.12 DM

(Note: The format of the date is MM/DD/YYYY!). This feature may be used to get an overview over the money you spend for the modem weekly or monthly. (See section Tools for a list of included programs to evaluate files containing call summary files.)

The format of the syslog message (option -syslog) has a different format:

Apr  2 00:34:22 moin tcharge[405]: Connection [Thu, 00:32:17]
 -> [Thu, 00:34:22], duration: 00:02:00,
Apr  2 00:34:22 moin tcharge[405]: units: 1, charge: 0.12 DM 

Tools

• summary
  Perl script that extracts date and money fields from a logfile (option -file) and lists charges monthly.
• summary.log
  Perl script to extract date and money fields from the syslog file and to list charges monthly.
• parse_logfile Perl script that uses tcharge in batch mode to calculate charges from pppd syslog messages (see options -start and -end).
• date2second
  Perl Script to generate time_t values from date/time. (Needed for options -start and -end.)
  To do the inverse: perl -e 'print scalar(localtime(<time_t value>)), "\n";')

Tcharge and PPP

As mentioned tcharge knows a "normal mode" and a "daemon mode". You can choose one of the two modes to run tcharge for PPP. I prefer the "normal mode" since the delays are better to handle using "normal mode": Then tcharge will be started automatically when the connection is up - much closer to what the telephone company thinks about your call than in "daemon mode" when watching the pid-file of the pppd. This pid-file will get created in the moment you start pppd, even before dialing! So I recommend:

• "Normal mode":Tcharge should be started immediately before or after a modem connection is up and should be killed after the connection terminates. If you use ppp you can configure the ip-up and ip-down scripts to do this automatically. Because it takes a while till the connection is established after the modem starts dialing (and consumes phone time in this time), we have to add a correction time via the -before option. Since there is also a delay between termination of the ppp connection and hang-up of the modem, so we have to use the -after option also. (Find out the delays by looking at /usr/adm/messages!) Guess why there are two options for delays and not one e.g. `-longer' option!

Here an example /etc/ppp/ip-up script (executed automatically by pppd when the connection is established). Note: tcharge tries to write a PID file (standard is /var/run/tcharge.pid). This is only possible if tcharge is executed by the superuser. Since usually pppd has superuser privileges, this should be no problem.

Here an example /etc/ppp/ip-down script (executed automatically by pppd when the connection is terminated):

• "daemon mode":
  There may be reasons that you can't go the way described above. For example, if you are using PPP in connection with ISDN, pppd would not start the ip-up script (but in this special case there is a better possibility; see section ISDN). Or you might want tcharge to stay on your desktop for the entire X-session. Then you must use the "daemon mode".

For completeness a short ip-up for daemon mode is provided. The only thing the ip-up script must do then is to ensure that tcharge actually is started when pppd gets up. For that the script tests if it is and starts tcharge when it is not.

Tcharge and ISDN

If tcharge is compiled with the `-DISDN' flag (see Makefile) you cannot choose the -watch-file option anymore and you have to take the -isdn option instead. This one may call a bug but I thought the `-watch-file' option is not useful for ISDN users (if you don't agree, tell me about). I don't have access to ISDN, so I'm not able to test anything (let's trust on Tillmann and his pppcosts-code!-)

It's possible to extract much more detailed information from the Linux ISDN driver `isdn4linux'. If you want to use this feature, I recommend you to use the program isdnlog by Andreas Kool akool@Kool.f.EUnet.de (For questions concerning isdnlog use this address: isdnlog@Kool.f.EUnet.de)

Files

Support

There is also a mailing list for tcharge. It is open, so everyone can directly post to the list. Yet everyone who wants to susbscribe to the list is welcome. To subscribe to the list send an e-mail with no subject and with the body

subscribe your@email.address
to tcharge-request@hix.physik.uni-bremen.de

To unsubscribe send an e-mail with the body

unsubscribe your@email.address

to the same address. If you want to send some mail to the list, send it to

tcharge@hix.physik.uni-bremen.de

For more information about this list's listserver send a mail with the body `help' to `majordomo@hix.physik.uni-bremen.de'. The list is intended for discussion of tcharge, bug reports, help requests and announcements of new releases, fixes, etc. (only the mails about new releases will also be send to the newsgroup comp.os.linux.announce).

Charge Modules

You are encouraged to test the charge definition files that tcharge provides and to help improving them.
The charges that a modem produces are of course highly dependent on your telephone company (TC). Though tcharge supports a lot of TCs (thanks to pppcosts!) there is still a lot to do since in most cases there is something missing e.g. a complete list of public holidays, support for more than the local area zone... And of course the charge definitions are not correct forever; check if they need an update! I hope things will still get better: Nearly all TC-dependent information is kept in single `charge files' that are easy to edit (and to create) also for "non-hackers". (Actually you don't have to know anything about programming!).
Included in the source is a perl script mktc that helps a lot to configure tcharge for another TC (see README.TC).

Bugs

Author

Volker Börchers boercher@physik.uni-bremen.de

Most X stuff is taken from rclock (version 1.81) written by: Rob Nation nation@rocket.sanders.lockheed.com

The idea for the "daemon mode", the ISDN-support as well as the support for most of supported countries is derived from `pppcosts', (pppcosts by Tillmann Steinbrecher tst@bigfoot.com, see
this link)

Thanks to Sascha Ziemann (szi@aibon.ping.de), George Antani(pitura@geocities.com), Oliver Gading (o.gading@sbu.ac.uk), Frank Kalberg (skywalker@devnull.owl.de), Michael.Schneider@vitrashop.com; special thanks to Heiko Brey (cthuga@www.netzservice.de) for our correspondence on the -noX option and a special console option (never realized...). Thanks to Michael Renner (renner@sunwan.mpik-tueb.mpg.de) - he found a bad bug in tcharge and was the "major beta tester" of version 1.3. Very much thanks to Markus Gutschke (gutschk@uni-muenster.de), author of `isdnbutton' for his help on the ISDN-support.