/*****************************************************************************
* TextCounter (C++ Version)     Version 1.3.1                                *
* Copyright 1996-98 Matt Wright mattw@worldwidemart.com                      *
* Created 03/14/96              Last Modified 06/24/98                       *
* Matt's Script Archive, Inc.   http://www.worldwidemart.com/scripts/        *
* Perl Version also available at Matt's Script Archive.                      *
******************************************************************************
* If you run into any problems while trying to configure this program, help  *
* is available.  The steps you should take to get the fastest results, are:  *
*       1) Read this file thoroughly                                         *
*       2) Consult the Matt's Script Archive Frequently Asked Questions:     *
*               http://www.worldwidemart.com/scripts/faq/                    *
*       3) If you are still having difficulty installing this program, send  *
*          e-mail to: scripts-help@tahoenet.com                              *
*          Include any error messages you are receiving and as much detail   *
*          as you can so we can spot your problem.  Also include the variable*
*          configuration block that is located at the top of the program.    *
*                                                                            *
* Hopefully we will be able to help you solve your problems.  Thank you.     *
******************************************************************************
* COPYRIGHT NOTICE                                                           *
* Copyright 1996-98 Matthew M. Wright  All Rights Reserved.                  *
*                                                                            *
* TextCounter may be used and modified free of charge by anyone so long as   *
* this copyright notice and the comments above remain intact.  By using this *
* code you agree to indemnify Matthew M. Wright from any liability that      *
* might arise from its use.                                                  *
*                                                                            *
* Selling the code for this program without prior written consent is         *
* expressly forbidden.  In other words, please ask first before you try and  *
* make money off of my program.                                              *
*                                                                            *
* Obtain permission before redistributing this software over the Internet or *
* in any other medium.  In all cases copyright and header must remain intact.*
*****************************************************************************/

TextCounter 1.3.1 is a simple program which allows you to include a counter
on any web page.  You can also include the date since it began counting, a 
link to a help page, digit padding, and more.  This program was designed for 
anyone to use, from a user who just wants a text counter on his or her home
page to a system administrator who wants to make it easy for anyone on their
server to use the counter program.  Multiple counters can be set up, with the
need for only one program to manage them all.  You can specify what
directories are allowed to access this program, and can even allow certain
directories or exclude certain directories from being able to use this script.
Details on how to install and use this script are available below.

Version 1.3 now allows a QUERY_STRING to be appended to the CGI program call,
in which case that name will be used as the file to store to rather than the
DOCUMENT_URI.  This allows the textcounter to work on servers which don't
support the DOCUMENT_URI environment variable.  I have heard some Netscape
servers to not support this, and thus you may need to use the QUERY_STRING.

A Perl version of this counter is also available at Matt's Script Archive,
however for frequently used programs such as a counter, C++ definitely has
an advantage over Perl.  I ran a few tests (nothing extremely standard) and
found that the C++ version runs about 5 times faster, at about .03 seconds,
compared to the Perl version which runs in about .15 seconds.

This package should have come with 2 files:
      1) README       - This file.  Installation Instructions, Disclaimer, 
                        Copyright, etc...
      2) tcounter.cpp - The C++ CGI program which does all of the work.
      3) convert.pl   - Converts data filenames from v1.3 to 1.3.1

Upgrading (from v1.3 to v1.3.1):
================================

If you do *not* already have v1.3 installed and running, please skip ahead to
the Installation section.  Otherwise, you should read this guide for 
upgrading to version 1.3.1 from 1.3.  First, configure all variables in 
tcounter.cpp as you have them currently set in the version you are using.
Before making this version live, however, place the convert.pl perl script
into the data directory where all of your textcounter data files are located
and run it to update the filenames.  It lets you verify which ones you wish
to change names on, in case you have other files in your data directory.

Now, replace your current running version of tcounter.cpp with the new version
where all variables are configured, compile it and all should work fine, 
security hole plugged.

Installation:
=============

tcounter.cpp
------------

There are several Variables and Options you will need to configure.  
The instructions below provide examples and instructions of how to do so.

VARIABLE CONFIGURATION:
      const char data_dir[] = "/path/to/data/";
            The data_dir variable should specify the path to the 
            directory under which all of the data files will be stored.
            This path must end with a '/' and it NEEDS to be writable by 
            your web server.  This means that you most likely will need 
            to chmod this directory 666.  You can do this by executing:

                  chmod 666 /path/to/data/

            It is suggested that you make a new directory for the sole
            purpose of holding the data files.  A new data file will be
            created for each page you add your text counter to.  You 
            may think that this is not the best way to do this, but it
            is not all bad, and is beneficial in some ways:

                  1) If you use this system wide, it is likely that 
                     many pages will load at the same time, meaning 
                     this program would have to try and edit the main 
                     file if it was all included in one database.  
                     This file can lead to slow downs (if I locked the
                     file each time it was called) or it could lead to 
                     mangled data if I didn't.  That is one reason I 
                     chose to use separate files.
                  2) The files created for the data are EXTREMELY 
                     small, taking up between 15 and 30 bytes (yes, 
                     you heard correctly, bytes).
                  3) Access time is faster as I know exactly what 
                     file to open, rather than flipping through lines 
                     of a database if it was all in one file.
                  (BTW, this explanation was more for people who 
                  may have questioned why I chose to do it this way.  
                  Most of you could care less about these last 3 points)
                  :-)

      const int  num_valid_uri = 0;
      const char valid_uri[num_valid_uri][128] = { };
            The valid_uri array allows you to allow this program to 
            be used only under a certain directory of your server.  Say 
            your username is fred and you are on a server called 
            host.com, therefore all of your pages reside under: 
            http://www.host.com/~fred/.  You only want those pages under
            that directory to be able to use this program, so you set the 
            valid_uri array to { "/~fred" }; and the num_valid_uri to the
            number of directories you allow, or 1 in this case. To let 
            your friend joe use it, by set the valid_uri variable to:
            { "/~fred", "/~joe" }; and num_valid_uri to 2.  Or if you are
            a sysadmin who wants to allow everyone to use this program, 
            simply set this array to { "/" }; and num_valid_uri to 0 along
            with the num_invalid_uri to 0.  If your web server supports
            the environment variable DOCUMENT_URI, you will most likely
            wish to set this variable to:
                  const int  num_valid_uri = 1;
                  const char valid_uri[num_valid_uri][128] = { "/" };

      const int  num_invalid_uri = 0;
      const char invalid_uri[num_invalid_uri][128] = { };
            Most likely you will just comment this line out if you do 
            not wish to block access to a certain part of your server.
            But take the example of fred above.  He decides to be real 
            cool and open this program up to anyone on the server by 
            setting valid_uri to { "/" };  His arch enemy bob is also on 
            the server though, and fred despises him so much that he 
            wants to block access to this guy, cause bob is such a jerk.
            So fred sets his invalid_uri to { "/~bob" }; so bob can't use 
            his counter. MU HA HA HA.  I'm sure there are other cool uses
            for this too.  Like if you sell virtual domains and want to 
            charge people before they can use your counter program, you 
            put their URI in here until they pay or something.  I dunno. 
            The story was fun to write, and that's all that matters. :-)

OPTION SETTINGS:
      const char show_link[] = "http://www.worldwidemart.com/scripts/";
            If you put a URL into this option, then the actual number 
            returned by the TextCounter program will be linked to this 
            URL.  This is useful if you want to link to my site 
            (PLEASE?!) or link to a help page explaining how the user 
            on your system can set up their own text counter.  Or if 
            you just want to have a pointless link on your number.  
            Setting this to a null value of "" will take out the
            link.

      const int auto_create = 1;
            Suggested value here is 1, or else you will have to 
            create data files by hand.  This allows users who reside 
            under the valid_uri array to create a new counter for their 
            page simply by putting the Server Side Include reference into
            their page.  Otherwise the maintainer will have to create a 
            data file which looks like:

                  0 January 1, 2000

            Obviously putting the correct date into the program and 
            changing 0 to whatever you want to start the number at.  
            This file MUST be writable by the web server meaning you 
            need to chmod it 666.  This means other users on your 
            system can write to it too, which is another reason to allow 
            auto-create.  Auto-Create will leave it chmoded so only the 
            web server can write to it. (usually)

      const int show_date = 1;
            If this variable is on, then the date on which you began 
            the count will appear with your actual count number.  It 
            will look like: 

                  [Count] hits since [Date]

            If this is turned off, you allow users more control over 
            their text and it will simply print:

                  [Count]

            The user can then supply the date if they wish.

      const int lock_sec = 2;
            The lock_sec variable defines how long the program will
            wait for the lock file to be cleared out, before
            overwriting the current lock file.  Often times, the
            count file would get overwritten in the older versions
            because there were no locks on the files, and when two
            users accessed at once, it messed things up.

            There are now built in lock routines, but if a user stops
            the process or your machine gets turned off or re-booted 
            while the lock file is still in the directory, that lock 
            file needs to get removed somehow.  The lock_sec variable
            tells the program how long it should wait before deciding
            that the lock file is not valid.

            Most of the time the program should not take longer than .1
            seconds to execute, but to be safe I set the default to 
            about 2 seconds in case you're on a REALLY slow server.
            You can vary this depending on whether you think your
            system will operate much faster or slower, but it must be
            a whole number, and I wouldn't go below 1.

      const int pad_size = 5;
            You will notice if you have seen many other counters on 
            the web, graphical or text-based, that they are often 
            padded with zeros at the front to form a number like: 
            0000154.  This is achieved by adding 0's to the front of 
            the current count.  In Version 1.3, you can specify how many
            digits long you want your number to be, so in the example 
            above you would set pad_size to 7;

            If you do not want your number padded and wish for the 
            above example to appear as 154 in your page, then set 
            pad_size = 1;

______________________________________________________________________________

COMPILING THIS PROGRAM

This program was written to compile on a BSDI BSD/OS version 2.1 with the
g++ compiler.  In order to compile it and get it ready for execution:

g++ tcounter.cpp
mv a.out tcounter

You can change tcounter above to tcounter.cgi if you need .cgi extensions for
CGI programs to work on your web server.

I tried to compile under MS Visual C++ Version 4.0 and received several
errros.  If you wish trun it under Windows and use MS Visual C++ to compile,
you will need to remove reference to unistd.h at the top and remove the
check_lock and cleanup subfunctions.  I also received errors of allocating
arrays of constant size 1, so you may need to find a work around for that.
I have no idea how it compiles under other OS's, however I would like to know
if it works or not for you.

If the compiling and stuff doesn't work out, an easier way of getting a
TextCounter for your web page may be to go to Matt's Script Archive and
download the Perl version.
______________________________________________________________________________

HOW TO CALL THIS PROGRAM FROM YOUR PAGE

Calling this program is really very simple.  As I have mentioned before, 
you will need Server Side Includes turned on on your server before you 
can use this program.  Talk to your system administrator or visit my 
Frequently Asked Questions section for more information on server side 
includes.  If you know they are turned on, or want to try and find out, 
put the following code into your HTML document:

<!--#exec cgi="/url/path/to/tcounter"-->

OR

<!--#include virtual="/url/path/to/tcounter"-->

So, if I have my tcounter (or tcounter.cgi if I have to rename it for 
my server) program located at 
http://www.worldwidemart.com/scripts/demos/textcounter/tcounter, then I 
would put the following into any HTML document a wanted a count to appear in:

<!--#exec cgi="/scripts/demos/textcounter/tcounter"-->

OR

<!--#include virtual="/scripts/demos/textcounter/tcounter"-->

Version 1.3 also allows the program to be called with a QUERY_STRING, unless
valid_uri has been set.  If valid_uri has been set, your system supports 
DOCUMENT_URI anyway, and this is not needed.  However, for servers that don't
support the DOCUMENT_URI environment variable, you can call your program as:

<!--#include virtual="/scripts/demos/textcounter/tcounter?unique_id"-->

Where unique_id is a string of characters that will be used as the filename
for your count.  The QUERY_STRING option could also be used to keep a count
of your entire site.  For instance, if you put the following on all your
pages:

<!--#include virtual="/scripts/demos/textcounter/tcounter?unique_id"-->

Where unique_id stays the same on each page you place the counter on, that
same count file woudl be used to count all your web site's web pages and
you could have a counter for your entire web site.
_____________________________________________________________________________

Well, that covers all of the options and variables, and I explained these 
in such detail that hopefully I won't get swamped by help mail for this 
program. :-D (Yah right!)  But please, before you ask for help, follow the 
steps at the top of this document.  You probably won't get an answer from 
myself or the help staff if your answer is in the Frequently Asked 
Questions at my site.
_____________________________________________________________________________

HISTORY:
Version 1.0  - 03/14/96 -      * TextCounter Created and Released.
Version 1.1  - 04/25/96 -      * @valid_referer array and checking 
                                 removed.  Because server side includes can 
                                 only be used locally, it is unnecessary.  
                                 Also, it was causing many counters to 
                                 incorrectly display error messages.
Version 1.2  - 05/10/96 -      * File Locking Procedure added.
                               * Options lock_sec and pad_size added.
Version 1.3  - 03/29/97 -      * Perl version converted to this C++ version.
                               * QUERY_STRING support added.
Version 1.3.1- 06/24/98 -      * SECURITY HOLE PLUGGED:
                                 Users could tack on extra commands to the
                                 DOCUMENT_URI URL and the script did not
                                 adequately check this input.
                               * This changed data filenames, so I included
                                 a convert.pl file which will convert
                                 v1.2 filenames into v1.2.1 filenames.
                               * De-allocated some memory that was allocated
                                 and never deleted in v1.3
_____________________________________________________________________________
Matt Wright - mattw@worldwidemart.com - http://www.worldwidemart.com/scripts/
