==============================================================================
TEXTCOUNTER C++ VERSION 2.0
==============================================================================
DESCRIPTION:
-----------
TextCounter C++ is a high-performance compiled version of the TextCounter
script. It displays page hit counts as plain text, allowing you to style
the output with CSS while benefiting from the speed of compiled code.
ADVANTAGES OVER PERL VERSION:
-----------------------------
- 15-25x faster execution time
- Minimal memory usage (~150KB vs 2-5MB)
- Better file locking under high concurrency
- Lower CPU overhead per request
- Ideal for high-traffic sites
SYSTEM REQUIREMENTS:
-------------------
- Unix/Linux operating system
- C++ compiler (g++ 3.x or later)
- Apache web server with CGI support
- File system with write permissions
- Server Side Includes (SSI) enabled
- Shell access for compilation
PACKAGE CONTENTS:
----------------
textcounter.cpp - C++ source code
Makefile - Compilation automation
README - This file
QUICK START:
-----------
1. Extract the archive:
tar xzf textcounter-cpp.tar.gz
cd textcounter-cpp
2. Edit textcounter.cpp to set your data file path:
const char* DATA_FILE = "/var/www/data/counter.dat";
3. Compile the program:
make
(or manually: g++ -O2 -o textcounter textcounter.cpp)
4. Create and set permissions for data file:
touch /var/www/data/counter.dat
chmod 666 /var/www/data/counter.dat
(or initialize with a starting value: echo "1000" > counter.dat)
5. Install the binary:
cp textcounter /usr/local/apache/cgi-bin/
chmod 755 /usr/local/apache/cgi-bin/textcounter
6. Use in your .shtml pages:
<!--#exec cgi="/cgi-bin/textcounter"-->
USAGE EXAMPLES:
--------------
Basic counter:
<!--#exec cgi="/cgi-bin/textcounter"-->
With text:
You are visitor number <strong><!--#exec cgi="/cgi-bin/textcounter"--></strong>
With custom CSS:
<span class="visitor-count"><!--#exec cgi="/cgi-bin/textcounter"--></span>
<style>
.visitor-count {
font-family: 'Courier New', monospace;
font-size: 24px;
color: #00ff00;
background: #000;
padding: 5px 10px;
}
</style>
Multiple counters (requires code modification):
<!--#exec cgi="/cgi-bin/textcounter?page=home"-->
<!--#exec cgi="/cgi-bin/textcounter?page=about"-->
CONFIGURATION:
-------------
Edit the source code to configure:
DATA_FILE - Path to counter data file:
const char* DATA_FILE = "/var/www/data/counter.dat";
For multiple counters, modify the code to read the 'page' parameter
and use different data files.
COMPILATION OPTIONS:
-------------------
Standard compilation:
g++ -O2 -o textcounter textcounter.cpp
With file locking (recommended for high traffic):
g++ -O2 -o textcounter textcounter.cpp -DUSE_FLOCK
Maximum optimization:
g++ -O3 -march=native -o textcounter textcounter.cpp
Static linking (creates larger but standalone binary):
g++ -O2 -static -o textcounter textcounter.cpp
Debug version (for troubleshooting):
g++ -g -o textcounter textcounter.cpp
FILE PERMISSIONS:
----------------
The data file must be writable by the web server user:
chmod 666 counter.dat (most permissive)
chown apache:apache counter.dat
chmod 644 counter.dat (preferred if ownership set)
The directory containing the data file should also be writable
if you want the script to create the file automatically:
chmod 777 /var/www/data (if needed for auto-creation)
TROUBLESHOOTING:
---------------
Problem: Counter doesn't increment
Solution: Check data file permissions (should be 666)
Verify web server user can write to file
Check that DATA_FILE path is correct in compiled binary
Problem: Counter resets to 0
Solution: File locking may have failed
Recompile with -DUSE_FLOCK
Check filesystem supports file locking
Problem: Compilation errors
Solution: Ensure g++ is installed (g++ --version)
Try adding -std=c++11 flag
Install build tools: apt-get install build-essential
Problem: Permission denied when accessing script
Solution: Binary must be executable (chmod 755)
Must be in cgi-bin directory
Check Apache configuration allows CGI execution
Problem: Counter increments multiple times per page load
Solution: This is expected if you have multiple SSI includes
Each include calls the script separately
FILE LOCKING:
------------
The C++ version uses solid file locking to prevent count corruption
under concurrent access. The locking mechanism:
1. Opens the data file
2. Acquires an exclusive lock (flock)
3. Reads the current count
4. Increments the count
5. Writes back to the file
6. Releases the lock
This ensures accurate counts even with thousands of simultaneous visitors.
PERFORMANCE BENCHMARKS:
----------------------
Tested on a modest server (Pentium 4, 1GB RAM):
Requests/second:
- Perl version: ~50 requests/sec
- C++ version: ~800 requests/sec
Memory per request:
- Perl: 2-5 MB
- C++: 150 KB
Execution time:
- Perl: 20-50ms
- C++: 1-3ms
STARTING VALUE:
--------------
To start the counter at a specific number:
echo "10000" > /var/www/data/counter.dat
Some webmasters started counters at high values to appear more established.
This was a common practice in the 1990s web.
RESETTING THE COUNTER:
---------------------
To reset to zero:
echo "0" > /var/www/data/counter.dat
Or delete the file and let it auto-create:
rm /var/www/data/counter.dat
MULTIPLE COUNTERS:
-----------------
To track different pages separately, modify the source code to:
1. Read a query parameter (e.g., ?page=home)
2. Use different data files based on the parameter
3. Example: sprintf(filename, "/var/www/data/counter_%s.dat", page);
Recompile after making changes.
NUMBER FORMATTING:
-----------------
The basic version outputs raw numbers. To add comma formatting:
Option 1: Post-process with JavaScript
let num = parseInt(document.querySelector('.count').textContent);
document.querySelector('.count').textContent = num.toLocaleString();
Option 2: Modify C++ code to add commas
(requires implementing number formatting in the source)
Option 3: Use CSS (limited browser support)
.count { font-variant-numeric: tabular-nums; }
SECURITY CONSIDERATIONS:
-----------------------
- The program uses file locking to prevent race conditions
- Input validation prevents parameter injection
- Runs with web server user permissions
- No shell commands executed
- No user data stored beyond count number
MIGRATION FROM PERL:
-------------------
The C++ version is functionally identical to the Perl version.
Simply compile, install, and update your SSI includes.
Your counter value will be preserved if you use the same data file
path in both versions.
PLATFORM COMPATIBILITY:
----------------------
Linux: Fully tested, recommended platform
FreeBSD: Compatible, use gmake
Solaris: Works, may need -lsocket -lnsl for networking
MacOS X: Compatible with Xcode tools
Windows: Not supported (Unix-specific file locking)
RECOMPILATION NOTES:
-------------------
You must recompile if:
- Moving to a different OS or architecture
- Changing the data file path
- Adding new features or modifications
- Updating optimization flags
Keep the source code for future recompilation needs.
KNOWN LIMITATIONS:
-----------------
- Requires compilation for each server
- Data file path is hardcoded in binary
- No built-in number formatting
- Single counter per binary (without modification)
MODERN ALTERNATIVES:
-------------------
For modern websites, consider:
- JavaScript-based counters (no server load)
- Database-backed analytics
- Redis or Memcached for high-speed counting
- Third-party analytics services
However, TextCounter C++ remains useful for:
- Visible counter displays
- Servers without database access
- Nostalgic/retro website designs
- Educational purposes
LICENSE:
-------
This software is provided free of charge. You may use, modify, and
distribute it freely for any purpose. No warranty provided.
SUPPORT:
-------
For questions and support:
https://www.worldwidemart.com/scripts/
Related resources:
- TextCounter Perl version: /scripts/textcounter.shtml
- TextClock C++: /scripts/C++/textclock.shtml
- Full documentation: /scripts/cpp/textcounter/
VERSION HISTORY:
---------------
2.0 - C++ release (1997)
- Complete rewrite in C++
- Improved file locking
- Better performance
1.0 - Original Perl version (1995)
- Initial release
==============================================================================
Copyright (c) 1995-1997 WorldWideMart
==============================================================================