ssd's C counter page

Status: Complete, no bugs. See below.
This page mostly documents how to use the C version of the counter, but there is also a section for the counter's source code and a To Do list that I sometimes update.

If you haven't read the top level counter page and the counter rules page, please do so now, especially the section on acceptable usage in the rules page.

Revision history:

22-Jul-95: updated README and added scripts/ to the source tar; all scripts in the scripts/ directory are also in the http directory, as they are currently being updated frequently; several new scripts may also be there.
21-Jul-95: Installed C counter on www-mae.engr.ucf.edu; added 'setvals' to counter source dir, began writing more accounting scripts
28-Jun-95: c counter created
12-Jul-95: a handful of very minor bug fixes were applied; README added to tar archive; default action is now INCREMENTSHOW instead of INCREMENT

Note: The perl counter is still in place--these features do not YET work with the url's given below. Perhaps by Monday...

Documentation

(The documentation here is in the process of being reformatted.)

Place something like this in your page:

  <!-- http://www-mae.engr.ucf.edu/~ssd/counter.html -->
  <img src="http://yoursite/counter?TAG&OPTIONS">

Where TAG is either a unique string identifying you or your page, or one of the special tags listed below. Please keep your tags short (say, less than 20 characters) so the database doesn't grow too big too quickly. Don't use a URL for a tag--there's lots of redundant info in a URL. If this becomes a problem, I'll disable all counters using URL's for tags.

The & is not needed if you use no options.

The following are always rejected as tags:


	font=	  increment	index	index.html
	noshow	  number	value	width=
	welcome	  welcome.html

The following tags are special:

digits: returns all digits in the current font
random or rand: returns a random number
any tags starting with a digit: display tag as a number

Note that the special tag xxxx is not accepted by the C version of the counter.

The following options are always valid:

width=: specify minimum number of digits to display in the count; implies show
font=: specify what font to use (odometer, digital); implies show Currently available fonts: odometer, digital

The following options are only valid with normal tags:

number: interpret tag as a number
noinc or value: only show the value for tag, don't increment
increment: increment and show value for tag
show: at least show value for tag
noshow: increment tag only

Source code

Many people have sent me ideas, but very few have sent me any code. If you'd like to see a new feature, I'll accept ideas, and I'd love code. :) See the To do... section below for a list of things that might get implemented in the future. If your idea got left out, send me mail and remind me about it!

I have put the C counter files all in one directory now. The files in this directory so far are:

src-c C counter source directory itself
counter.tar.gz the counter source
showtags show the tag database
showurls show the URL database
showurls show lots of tag info

Note that the list above is not maintained regularly--check the directory (first listed above) directly. Please let me know if you have troubles with any of this. Also, the tar file may not have the most up to date utility scripts in it. You can pick up updates from the directory if you want.

I have shamelessly stolen the gif encoder in the C counter from ppmtogif. The copyright notice for the gif encoder follows:

Based on GIFENCOD by David Rowley <mgardi@watdscu.waterloo.edu>
Lempel-Zim compression based on "compress".
Modified by Marcel Wijkstra <wijkstra@fwi.uva.nl>
Copyright (C) 1989 by Jef Poskanzer.
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.
The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated.

Portability

The C version should be slightly more portable than the perl version since it does not have to call any external programs. Areas most likely to cause problems are:

File locking: I have offered three alternative file locking methods. Most systems should support POSIX locking. If your system doesn't work with any of the three I have provided, please add another one and send me the patches. If you are sure more than one counter will never be run at a time, you can disable locking completely. I have begun to suspect that the locking is redundant. I think some implementations of ndbm do their own internal locking.
dbm database: Non-unix systems may not have dbm, and dbm may be buggy on such systems such as AUX. On HPUX and possibly other systems, you should use ndbm instead of dbm. If that doesn't help, I suggest you try gnu gdbm (available on any gnu archive site) if your system either doesn't have dbm or if you suspect yoru system's dbm is buggy. If your dbm is definately buggy, let me know so I can make a list of such systems.
unix time(): Most systems support unix style time() which returns time in seconds, but there are a few non-unix systems that do not support this. You may have to find an alternate way to handle timestamps or comment out that section of code.

To Do...

Send me any ideas you'd like to see implemented, or individual images of digits you'd like to have added as a font. Font addition is now trivial if each digit is a separate image. Note that I think the existing digits are cool--I'm not looking for a replacement. If I add another font, it will be because the new digits are differently cool. Someone suggested a nixie tube font--I'm thinking about this, and if I draw something cool or someone sends me something, I might add it.

write accounting scripts similar to perl version scripts
modify the URL parser to reject malformed REFERER urls
make it easy to add more rejection pictures
write 99% automated code to implment usage policy
add #ifdef's to the C code to restrict creation of new counters
add nph support
document counter server admin interfaces

to do eventually

design a syntax to specify color options
figgure out what to do about alternate format fonts (i.e. non-grey)
alarm code to reap dead network sockets
set up C version as stand alone single server instead of using httpd
- single server wouldn't have race conditions (no locking needed?)
- single server couldn't raise load above 1, and would not impact local www access speeds except to itself
- code independant from httpd could do its own rate based prioritizing when multiple connections came in at once (do local requests first, then provide for local counters, throttle back on counters being hit too often, etc.)
- stand alone server will require a different port number. Ick.
increase portability by moving config options in counter.c into a header file

People suggested these ideas...

but I have no intent to implement them--if you do, send me patches! I might change my mind later, and implement these anyway, but not this week. If you have code or implementation ideas, send 'em!

ability to restrict counters to a domain or require registration
ability to set the counter's value (with a form+password?)
ability to set an interval to reset the counter
ability to ask for a periodic status report to be automatically mailed

SSD 22-Jul-95