Open the file however you choose. Pass the filehandle to flock(), as on line 2. If another process is using the file, the second process should hang at the flock() command until the first process is done. That is all there is to it.

Excluding Unwanted Domains from Your Counts

Your counter is working wonderfully, your access counts are going up at a nice, steady pace, and then one dark and stormy night, your access counter goes BUMP in the night! Your count went from a daily change of 100 hits a day to 2,000 hits. What happened? Somebody decided to play with your CGI counter and called it 2,000 times just to mess up your counts or just for the fun of it.

You can stop these unwanted counts rather easily. First, you must figure out how your script is being called. You can find the domain from which the counter terrorist is attacking without any problem by looking in the access_log file. The easiest thing to do is to not count any hits from that domain. You do this by creating an array inside your CGI counter program that contains a list of all the domains and IP addresses that you don't want to count. Then you compare the array against the REMOTE_HOST and REMOTE_ADDR environment variables. For starters, I'll exclude access from my server to my Web pages. Listing 10.9 shows the array and code for excluding parts of the array.

Listing 10.9. Excluding unwanted counts.

1: @BAD-ADDRESSES="199.170.89","austin.io.com";
2: $increment-counter="true";
3: foreach $address  (@BAD-ADDRESSES){
4:     if( ($ENV{'REMOTE_ADDR'}=~ $address)||
5:         ($ENV{'REMOTE_HOST'}=~ $address)){
6:         $increment-counter="false";
7:         }
8:     }

The Perl pattern binding operator (=~)returns true if it finds the IP address or hostname and sets the increment-counter variable to false. In your code where you increment your counter, add this statement:

if (increment-counter eg "true"){
    counter++;
    }

Just add IP addresses and remote hosts as necessary to the @BAD-ADDRESSES array. You even can store the bad address in a file and then just read the file into the @BAD-ADDRESSES array at the start of your program. However you choose to do it, the basic steps are outlined in Listing 10.9.

Printing the Counter

Opening and closing files and understanding DBM files is a primary portion of creating your own counter. The next major portion is printing out the counter. You really have three choices:

• Simply print the value just like the SSI command in Listing 10.3.
• Create a fancy text format for your counter, as shown in Figure 10.5. This counter program is available at
  http://www.webbooks.org/counter
  The code that generated the output in Figure 10.5 is written in Perl and is available at this site also. The code is well commented, and you can look at it at your leisure.
• Generate one of those nifty graphics image counters, such as the one in Figure 10.6. There are several ways to do this. You will learn how to generate your own graphics images in the next section.

Figure 10.5 : A fancy text access counter.

Figure 10.6 : The W4 access counter.

Turning Your Counter into an Inline Image

Getting your counter to appear as an inline image is very simple; just add this HTML:

<img src=/cgi-bin/counter.cgi>

This makes your counter program run each time the Web page that contains it is called. All your CGI program has to do now is return a valid image.

Returning the image is what this section is all about. You can use three basic methods to return graphics images. In the first method, you use a bitmap to return the counter as a graphics image. The second method takes several prebuilt GIF images and strings them together to make one image. The third method uses an existing library for generating graphics images like the one called gd, which is written by Thomas Boutell.

Generating Counters from a Bitmap

You will start with where the Internet started. Most of the counters seem to use a design written by Frans Van Hoesel, whose e-mail address is hoesel@rug.nl. The original code was written in C but has been ported many times into Perl and other languages.

The code is based on two bitmaps that contain the hexadecimal values required to generate a GIF image. Usually, the code includes two bitmaps: one for inverse video images and one for regular video images. These bitmaps produce odometer-like images, as shown in Figure 10.6. This shows an image of the W4 consultancy's counter implemented by Heine Withagen. This site has a nice introduction to access counter basics at

http://sparkie.riv.net/w4/software/counter/index.html

The nice thing about understanding bitmaps is their versatility. After you learn how to use bitmaps to build odometer-like counters, you can use bitmaps to build any type of inline image.

Listing 10.10 shows the two arrays used to draw odometer-like counter images. You can find these two bitmaps at

http://picard.dartmouth.edu/HomePageCounters.html

This code was written by John Erickson and can be retrieved from the preceding Web page.

Listing 10.10. Odometer bitmaps.

01:   # bitmap for each digit
02:   #  Each digit is 8 pixels wide, 10 high
03:   #  @invdigits are white on black, @digits black on white
04:   @invdigits = ("c3 99 99 99 99 99 99 99 99 c3",  # 0
05:                 "cf c7 cf cf cf cf cf cf cf c7",  # 1
06:                 "c3 99 9f 9f cf e7 f3 f9 f9 81",  # 2
07:                 "c3 99 9f 9f c7 9f 9f 9f 99 c3",  # 3
08:                 "cf cf c7 c7 cb cb cd 81 cf 87",  # 4
09:                 "81 f9 f9 f9 c1 9f 9f 9f 99 c3",  # 5
10:                 "c7 f3 f9 f9 c1 99 99 99 99 c3",  # 6
11:                 "81 99 9f 9f cf cf e7 e7 f3 f3",  # 7
12:                 "c3 99 99 99 c3 99 99 99 99 c3",  # 8
13:                 "c3 99 99 99 99 83 9f 9f cf e3"); # 9
14:
15:
16:      @digits = ("3c 66 66 66 66 66 66 66 66 3c",  # 0
17:                 "30 38 30 30 30 30 30 30 30 30",  # 1
18:                 "3c 66 60 60 30 18 0c 06 06 7e",  # 2
19:                 "3c 66 60 60 38 60 60 60 66 3c",  # 3
20:                 "30 30 38 38 34 34 32 7e 30 78",  # 4
21:                 "7e 06 06 06 3e 60 60 60 66 3c",  # 5
22:                 "38 0c 06 06 3e 66 66 66 66 3c",  # 6
23:                 "7e 66 60 60 30 30 18 18 0c 0c",  # 7
24:                 "3c 66 66 66 3c 66 66 66 66 3c",  # 8
25:                 "3c 66 66 66 66 7c 60 60 30 1c"); # 9

You can create any image you want by sending out this HTTP response header:

print ("Content-type: image/x-xbitmap\n\n");

and then defining the width and height of the bitmap with this statement:

print("#define count_width $x-width\n#define count_height $y-height\n");

The variables $x-width and $y-height are the pixel width and height of the image you are going to display. The algorithms for printing the bitmap to the screen print the entire bitmap one row at a time. Listing 10.11 shows the program segment that builds the bitmap to be printed.

Listing 10.11. Building a displayable bitmap.

1:  $formatted-count=sprintf("%0${NUMBER-OF-DIGITS}d",$count);
2:  for($Y-POSITION=0; $Y-POSITION < $MAX-Y-HEIGHT; $Y-HEIGHT++){
3:      for($X-POSITION=0; $X-POSITION < $NUMBER-OF-DIGITS; $X-WIDTH++){
4:          $DIGIT=substr($formatted-count,$X-POSITION,1);
5:          $BYTE=substr(@NORMAL-BITMAP[$DIGIT],$Y-POSITION*3,2);
6:          push(@DISPLAY-BITMAP,$BYTE);
7:      }
8:      }

This program listing and the following one are drawn liberally with John Erickson's permission from the code described previously. As stated earlier, you need to draw one horizontal line at a time. In order to do this, you must traverse the bitmap in Listing 10.10 one horizontal piece of each digit at a time. And that is what Listing 10.11 does. You can use this basic algorithm to build any bitmap array you want.

In this case, you must figure out a way to pull from the bitmaps of digits in Listing 10.10 each piece of the digits that make up your counter. In order to do this, you need some reasonable way to access each digit a number of times. This is accomplished on line 1 of Listing 10.11.

The sprintf() function, when used in this manner, takes a number and returns a string that is the size of the variable $NUMBER-OF-DIGITS:

sprintf("%0${NUMBER-OF-DIGITS}d",$count);

If the formatted number is not as large as defined by the variable $NUMBER-OF-DIGITS, the returned string, $formatted-count, will be left filled with leading zeroes. This happens because of the zero (0) that follows the percent sign (%) in the sprintf statement.

The first for loop on line 2 loops one time for each pixel of height of the bitmap. The next for loop loops once for each digit in the bitmap. Line 4 gets the digit for this byte of the bitmap. Line 5 removes a single byte of information about what this digit looks like at a particular $Y-POSITION. The $Y-POSITION is multiplied by 3 to move through the @NORMAL-BITMAP array three characters at a time. Notice in Listing 10.10 that a single value is made up of two numbers and a space. The numbers are hexadecimal values; the space helps make the bitmap readable by humans. The substr() command takes the two numbers it needs, leaving the space character behind. The next time through the $Y-POSITION for loop, the space is skipped and the next number pair is fetched. Each $BYTE retrieved this way then is pushed onto an array of bytes for the @DISPLAY-BITMAP.

The @DISPLAY-BITMAP is processed in the next program fragment. Each digit adds its byte to the @DISPLAY-BITMAP on lines 3-7, and then the $Y-POSITION is incremented and the next row of bytes is added to the @DISPLAY-BITMAP until all the horizontal rows that make up the bitmap have been added to the @DISPLAY-BITMAP.

Next, the @DISPLAY-BITMAP is processed and sent to STDOUT for display as a GIF image. Some formatting of the @DISPLAY-BITMAP array is required before sending to STDOUT. This formatting is required because you used a bitmap that is easy to read by humans. Most of the formatting information added could be replaced by a bitmap that looks like the one in Listing 10.12.

Listing 10.12. A bitmap table formatted for output.

01: # bitmap for each digit
02: @invdigits = (0xff,0xff,0xff,0xc3,0x99,0x99,0x99,0x99,
03:        0x99,0x99,0x99,0x99,0xc3,0xff,0xff,0xff,
04:        0xff,0xff,0xff,0xcf,0xc7,0xcf,0xcf,0xcf,
05:        0xcf,0xcf,0xcf,0xcf,0xcf,0xff,0xff,0xff,
06:        0xff,0xff,0xff,0xc3,0x99,0x9f,0x9f,0xcf,
07:        0xe7,0xf3,0xf9,0xf9,0x81,0xff,0xff,0xff,
08:        0xff,0xff,0xff,0xc3,0x99,0x9f,0x9f,0xc7,
09:        0x9f,0x9f,0x9f,0x99,0xc3,0xff,0xff,0xff,
10:        0xff,0xff,0xff,0xcf,0xcf,0xc7,0xc7,0xcb,
11:        0xcb,0xcd,0x81,0xcf,0x87,0xff,0xff,0xff,
12:        0xff,0xff,0xff,0x81,0xf9,0xf9,0xf9,0xc1,
13:        0x9f,0x9f,0x9f,0x99,0xc3,0xff,0xff,0xff,
14:        0xff,0xff,0xff,0xc7,0xf3,0xf9,0xf9,0xc1,
15:        0x99,0x99,0x99,0x99,0xc3,0xff,0xff,0xff,
16:        0xff,0xff,0xff,0x81,0x99,0x9f,0x9f,0xcf,
17:        0xcf,0xe7,0xe7,0xf3,0xf3,0xff,0xff,0xff,
18:        0xff,0xff,0xff,0xc3,0x99,0x99,0x99,0xc3,
19:        0x99,0x99,0x99,0x99,0xc3,0xff,0xff,0xff,
20:        0xff,0xff,0xff,0xc3,0x99,0x99,0x99,0x99,
21:        0x83,0x9f,0x9f,0xcf,0xe3,0xff,0xff,0xff
22:        );
23:
24: @digits = (0x00,0x00,0x00,0x3c,0x66,0x66,0x66,0x66,
25:        0x66,0x66,0x66,0x66,0x3c,0x00,0x00,0x00,
26:        0x00,0x00,0x00,0x30,0x38,0x30,0x30,0x30,
27:        0x30,0x30,0x30,0x30,0x30,0x00,0x00,0x00,
28:        0x00,0x00,0x00,0x3c,0x66,0x60,0x60,0x30,
29:        0x18,0x0c,0x06,0x06,0x7e,0x00,0x00,0x00,
30:        0x00,0x00,0x00,0x3c,0x66,0x60,0x60,0x38,
31:        0x60,0x60,0x60,0x66,0x3c,0x00,0x00,0x00,
32:        0x00,0x00,0x00,0x30,0x30,0x38,0x38,0x34,
33:        0x34,0x32,0x7e,0x30,0x78,0x00,0x00,0x00,
34:        0x00,0x00,0x00,0x7e,0x06,0x06,0x06,0x3e,
35:        0x60,0x60,0x60,0x66,0x3c,0x00,0x00,0x00,
36:        0x00,0x00,0x00,0x38,0x0c,0x06,0x06,0x3e,
37:        0x66,0x66,0x66,0x66,0x3c,0x00,0x00,0x00,
38:        0x00,0x00,0x00,0x7e,0x66,0x60,0x60,0x30,
39:        0x30,0x18,0x18,0x0c,0x0c,0x00,0x00,0x00,
40:        0x00,0x00,0x00,0x3c,0x66,0x66,0x66,0x3c,
41:        0x66,0x66,0x66,0x66,0x3c,0x00,0x00,0x00,
42:        0x00,0x00,0x00,0x3c,0x66,0x66,0x66,0x66,
43:        0x7c,0x60,0x60,0x30,0x1c,0x00,0x00,0x00
44:        );

I think the extra work required to process the bitmap is worth the extra readability of the bitmap array in Listing 10.10, but this is really no more than a personal preference. You might prefer the lesser code required to process the bitmap in Listing 10.12. It can be processed simply by replacing line 5 of Listing 10.11 with this line:

$BYTE=substr(@NORMAL-BITMAP,[$DIGIT],$Y-POSITION*5,5);

$BYTE now contains 0xNN, where NN is some hexadecimal number. The @DISPLAY-BITMAP array generated from Listing 10.11 is turned into a GIF image printed on your screen by the program fragment in Listing 10.13.

Listing 10.13. Printing the bitmap.

01:  printf("Content-type:image/x-xbitmap\n\n");
02:  printf("#define count_width%d\n#define count_height10\n",
03:         $NUMBER-OF-DIGITS*8);
04:  printf("static char count_bits[]={\n");
05:  $SIZE-OF-DISPLAY-BITMAP=#DISPLAY-BITMAP; ;
06:  for($NUMBER-OF-BYTE=0;
07:      $NUMBER-OF-BYTE<$SIZE-OF-DISPLAY-BITMAP;
08:      $NUMBER-OF-BYTE++){
09:  print("0X$DISPLAY-BITMAP[$NUMBER-OF-BYTE],");
10:      if((NUMBER-OF-BYTE+1)%7==0){
11:          print("\n");
12:          }
13:      }
14:  print("0X$DISPLAY-BITMAP[$NUMBER-OF-BYTE]\n};\n");

This program fragment can be used to print any GIF image bitmap, as long as you define the width and height correctly. As always, you've got to print the Content-type response header. Don't forget the two newlines (\n\n) required after any ending response header. Then you actually print C code to STDOUT, defining the width and height of the GIF bitmap in pixels. Next, line 4 begins the definition of a C character array that will be loaded with the hexadecimal values that will generate your bitmap. Lines 6-13 load the bitmap one byte at a time into the character array started on line 4. Line 9 converts the two-digit string into the correct hexadecimal format by adding 0X before the two-digit number and a comma (,) after the number; this is the proper syntax for building a C character array made up of hexadecimal values (0XNN, for example).

The for loop on lines 6-13 prints out every byte of the @DISPLAY-BITMAP array except the last byte. The last byte requires special formatting, and line 14 provides that special formatting by taking advantage of the post increment of the for loop index $NUMBER-OF-BYTE. You always should use a for loop index with caution, because some languages don't guarantee the contents of for loop index variables after the loop executes. In this case, Perl maintains the value of $NUMBER-OF-BYTE for you. $NUMBER-OF-BYTE is not incremented after the loop fails and equals the value of the last byte in the @DISPLAY-BITMAP array. The byte does not require a trailing comma.

After the last element in the array, line 14 prints the last byte of the bitmap and then closes the array with the curly brace (}), prints a semicolon (;) to close the definition of the static character array, and finally prints a newline (\n) to close the definition of the GIF image.

And that's all there is to printing inline images made from bitmaps. Listing 10.14 shows a complete listing of all the concepts discussed so far, just so you can see everything put together. The program segment in Listing 10.14 works but is not really complete; error checking and options like increasing the size of the image aren't included in this example.

Listing 10.14. Printing an inline counter as an odometer, using a bitmap.

01: #chECK FOR ADDRESSES TO EXCLUDE FROM THE AccESS COUNT
02: @BAD-ADDRESSES="199.170.89","austin.io.com";
03: $increment-counter="true";
04: foreach $address  (@BAD-ADDRESSES){
05:     if( ($ENV{'REMOTE_ADDR'}=~ $address)||
06:         ($ENV{'REMOTE_HOST'}=~ $address)){
07:         $increment-counter="false";
08:         }
09:     }
10:
11: #OPEN THE AccESS COUNTER FILE AND IncREMENT THE COUNTER
12: dbmopen(%COUNTERS, $DOCUMENT-ROOT/DBM_FILES/counters,0666);
13: flock(COUNTERS,1);
14: if(!(defined($COUNTERS{'my_counter'})){
15:     $COUNTERS{'my_counter'}=0;
16:     }
17:
18: if (increment-counter eg "true"){
19:     $COUNTERS{'my_counter'})++;
20:     }
21:
22: $count=$COUNTERS{'my_counter'};
23: dbmclose (COUNTERS);
24: flock(COUNTERS,8);
25:
26: #BUILD THE BITMAP DISPLAY ARRAY
27: $formatted-count=sprintf("%0${NUMBER-OF-DIGITS}d",$count);
28: for($Y-POSITION=0; $Y-POSITION < $MAX-Y-HEIGHT; $Y-POSITION++){
29:     for($X-POSITION=0; $X-POSITION < $NUMBER-OF-DIGITS; $X-POSITION++){
30:         $DIGIT=substr($formatted-count, $X-POSITION, 1);
31:         $BYTE=substr(@NORMAL-BITMAP[$DIGIT], $Y-POSITION*3, 2);
32:         push(@DISPLAY-BITMAP, $BYTE);
33:         }
34:          }
35:
36: #PRINT THE BITMAP DISPLAY ARRAY
37: printf("Content-type:image/x-xbitmap\n\n");
38: printf("#define count_width%d\n#define count_height10\n",
39:     $NUMBER-OF-DIGITS*8);
40: printf("static char count_bits[]={\n");
41: $SIZE-OF-DISPLAY-BITMAP=#DISPLAY-BITMAP;
42: for($NUMBER-OF-BYTE=0;
43:     $NUMBER-OF-BYTE<$SIZE-OF-DISPLAY-BITMAP;
44:     $NUMBER-OF-BYTE++){
45:    print("0X$DISPLAY-BITMAP[$NUMBER-OF-BYTE],");
46:    if((NUMBER-OF-BYTE+1)%7==0){
47:         print("\n");
48:         }
49:     }
50: print("0X$DISPLAY-BITMAP[$NUMBER-OF-BYTE]\n};\n");

Using the WWW Homepage Access Counter

If you don't want to go to the trouble of generating images from your own bitmaps, several nice counters are available on the Net that you can use. The WWW Homepage Access Counter available at

http://www.fccc.edu/users/muquit/

is a nice implementation of the second method of including counters as inline images. WWW Homepage Access Counter uses prebuilt GIF images and concatenates them to generate a single GIF image, as shown in Figure 10.7. The program is written in C, and the code is available for you to look at on the Net. The original program was designed to run on a UNIX operating system, but it has been ported to most other platforms, including the Windows NT platform.

Figure 10.7 : The WWW Homepage Access Counter.

The WWW Homepage Access Counter keeps a record of the raw hits to a Web page. It generates a GIF image of the number of hits and returns to the browser an inline image of the number of hits. The program also has a runtime option to not show the digital images; this way, the hits can be recorded without displaying them. This program has a nice set of features that makes it different from most of the other inline counters.

The features of the WWW Homepage Access Counter 1.5 follow:

• SSI commands are not required.
• An ornamental 3D frame can be wrapped around the counter image with user-defined thickness and color.
• This program can be used for any number of Web pages.
• Any color of the counter image can be made transparent.
• The style of digits can be specified.
• Authorized hostnames can be placed in the configuration file.
• IP filtering is available through the configuration file.
• Advisory data file locking is available.
• A maximum number of digits can be set, or the counter can be displayed with an exact number of digits.
• A start-up counter value can be specified through the configuration file.
• The display of the counter can be turned off, while still maintaining a valid count of hits.

The WWW Homepage Access Counter uses a set of GIF images and enables you to choose the style you want to use as your Web page counter. This program has four installed digit styles, as shown in Figure 10.8, but you can use any image you want by adding your own digit style. A huge collection of GIF digits is available at the Digit Mania page at

Figure 10.8 : The digit styles of the WWW Homepage Access Counter.

http://cervantes.comptons.com/digits/digits.htm

This counter is great for its versatility but unfortunately is rather brittle. It uses a large set of parameters that must be passed via the QUERY_STRING. All the parameters must be included in the correct order, and they must be in lowercase. This produces the relatively complex link illustrated here:

<img src="/cgi-bin/
 Count.cgi?ft=9|frgb=69;139;50|tr=0|trgb=0;0;0|wxh=15;20|md=6|dd=A|st=5|sh=1|df=count.dat"

align=absmiddle>;

Table 10.5 shows the parameters required in the QUERY_STRING.

If you take the time to look at the code available with this counter, there is a nice little program called StringImage, available in a separate file called strimage.c, that creates an image from a string. This handy little subroutine is worth your investigation for its versatility in generating any type of image.

Using the gd 1.2 Library to Generate Counter Images On-the-Fly

The WWW Homepage Access Counter is a hybrid set of code that starts to take use of a graphics library specifically built for generating any type of graphics images on-the-fly. The WWW Homepage Access Counter performs part of the work itself by having a prebuilt set of GIF images. But it is possible to use the gd 1.2 graphics library, which is outlined in the next section, to take care of all aspects of the graphics display of counters.

Listing 10.15 shows the program count.c in its entirety because of its compactness and how well it illustrates using existing libraries to simplify complex tasks.

Listing 10.15. count.c-Using the gd 1.2 graphics library.

01: #include <stdio.h>
02: #include <stdlib.h>
03: #include <string.h>
04: #include "gd.h"
05: #include "gdfontl.h"
06: #include "gdfonts.h"
07: #include <time.h>
08: #include <sys/types.h>
09: #include <sys/stat.h>
10: /* Look for the file in this directory: */
11: #define HTML_DIR "/sparky.a/masters/reme7117/public_html/count/"
12:
13: /* This is what I use to test locally - ignore */
14: /* #define HTML_DIR "D:\\cgi-bin\\count\\WinDebug\\" */
15:
16: int main(
17: int argc, char *argv[])
18: {
19:     char html_dir[180] =    HTML_DIR;
20:     char *full_path;
21:
22:     /* Output image */
23:     gdImagePtr im_out;
24:
25:     /* Color indexes */
26:     int bg_color;
27:     int fore_color;
28:
29:     FILE *fp = NULL;
30:     int access_count;
31:     char count_string[8];
32:     char template[9]= "00000000";
33:     int i, k;
34:
35:     full_path = strcat(html_dir, argv[1]);
36:     if(argc!=2)
37:         {
38:         printf("Content-type: text/plain%c%c",10,10);
39:         printf("Problem getting information: No file name specified");
40:         return(1);
41:         }
42:
43:     /* Create output image, 67 by 18 pixels. */
44:     im_out = gdImageCreate(67, 18);
45:
46:     /* Allocate the colors */
47:     bg_color = gdImageColorAllocate(im_out, 0, 0, 0);
48:     fore_color = gdImageColorAllocate(im_out, 255, 255, 255);
49:
50:     /* Set transparent color. */
51:     /* gdImageColorTransparent(im_out, bg_color); */
52:     /* Get the current count */
53:
54:     fp = fopen(full_path,"r");
55:     fgets(count_string, 8, fp);
56:     fclose(fp);
57:
58:     /* Increment the count and write it back to the file */
59:     sscanf(count_string,"%d",&access_count);
60:     access_count++;
61:     fp = fopen(full_path,"w");
62:     fprintf(fp,"%d",access_count);
63:     fclose(fp);
64:
65:     /* Put formated string in output buffer */
66:     for (i=8-strlen(count_string), k=0; i<8; i++, k++)
67:           template[i] = count_string[k];
68:
69:     /* Write the count string */
70:     gdImageString(im_out, gdFontLarge, 2, 1, template, fore_color);
71:
72:     /* Make output image interlaced
73:                  (allows "fade in" in some viewers, and in the latest Web
  browsers) */
74:     gdImageInterlace(im_out, 1);
75:
76:     /* Write MIME header */
77:     printf ("Content-type: image/gif%c%c",10,10);
78:
79:     /* Write GIF */
80:     gdImageGif(im_out, stdout);
81:
82:     /* Clean up */
83:     gdImageDestroy(im_out);
84:
85:     return 0;
86: }

This program and a similar one called count2.c are available at

http://sparky.cs.nyu.edu:8086/cgi.htm

Unfortunately, this program provides very minimal support for the features you would like to find in access counters. File locking is not available, and neither is domain filtering. If you use this code, I recommend that you add both these features to your own version of count.c. Nevertheless, this is an excellent starting place for a straightforward and easy-to-understand image-producing access counter. The gd 1.2 library that this program makes such heavy and excellent use of is explained in the following section.

Using the gd 1.2 Library to Produce Images On-the-Fly

gd is a graphics library written in C by Thomas Boutell and available at

http://www.boutell.com/gd/

It enables your code to quickly draw images, complete with lines, arcs, text, and multiple colors; to cut and paste from other images; to flood fills; and to write the result as a GIF file. Use this section as a handy reference guide to Tom's gd 1.2 library.

gd is not a paint program, however. If you are looking for a paint program, try xpaint by David Koblas, available at

ftp://ftp.netcom.com/pub/ko/koblas

This package is for the X Window System; paint programs for the Mac and the pc are considerably easier to find.

To use gd, you need an ANSI C compiler. Any full-ANSI-standard C compiler should be adequate, although those with pcs will need to replace the makefile with one of their own. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Get gcc, which is freely available on the Net. See the Sun-related newsgroups for more information.

You also will want a GIF viewer for your system, because you will need a good way to check the results of your work. lview is a good package for Windows pcs; xv is a good package for X11. GIF viewers are available for every graphics-capable computer out there, so consult newsgroups relevant to your particular system.

The gd library enables you to create GIF images on-the-fly. To use gd in your program, include the file gd.h and link with the libgd.a library produced by make libgd.a under UNIX. You need to adapt the makefile for your needs if you are using a non-UNIX operating system, but this is very straightforward.

If you want to use the provided fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h, and/or gdfontg.h. If you are not using the provided makefile and/or a library-based approach, be sure to include the source modules as well in your project. Listing 10.16 shows a short example of how to use the gd libraries. A more advanced example, gddemo.c, is included in the distribution.

Listing 10.16. Using the gd library.

01: /* Bring in gd library functions */
02: #include "gd.h"
03:
04: /* Bring in standard I/O so we can output the GIF to a file */
05: #include <;stdio.h>;
06:
07: int main() {
08:     /* Declare the image */
09:     <A HREF="#gdImagePtr">gdImagePtr im;
10:     /* Declare an output file */
11:     FILE *out;
12:     /* Declare color indexes */
13:     int black;
14:     int white;
15:
16:     /* Allocate the image: 64 pixels across by 64 pixels tall */
17:     im = <A HREF="#gdImageCreate">gdImageCreate(64, 64);
18:
19:     /* Allocate the color black (red, green and blue all minimum).
20:         Since this is the first color in a new image, it will
21:         be the background color. */
22:     black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate(im,
  0, 0, 0);
23:
24:     /* Allocate the color white (red, green and blue all maximum). */
25:     white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate(im, 255,
  255, 255);
26:
27:     /* Draw a line from the upper left to the lower right,
28:         using white color index. */
29:     <A HREF="#gdImageLine">gdImageLine(im, 0, 0, 63, 63, white);
30:
31:     /* Open a file for writing. "wb" means "write binary", important
32:         under MSDOS, harmless under UNIX. */
33:     out = fopen("test.gif", "wb");
34:
35:     /* Output the image to the disk file. */
36:     <A HREF="#gdImageGif">gdImageGif(im, out);
37:
38:     /* Close the file. */
39:     fclose(out);
40:
41:     /* Destroy the image in memory. */
42:     <A HREF="#gdImageDestroy">gdImageDestroy(im);
43: }

When executed, this program creates an image, allocates two colors (the first color allocated becomes the background color), draws a diagonal line (note that 0,0 is the upper left corner), writes the image to a GIF file, and destroys the image.

Global Types

The gd library uses several global types for communication between its functions. These types are used to communicate the structure of fonts and images and to point to those structures.

gdFont

gdFont is a font structure used to declare the characteristics of a font. See the files gdfontl.c and gdfontl.h for examples of the proper declaration of this structure. You can provide your own font data by providing such a structure and the associated pixel array. You can determine the width and height of a single character in a font by examining the w and h members of the structure.

gdFontPtr

gdFontPtr is a pointer to a font structure. Text-output functions expect this as their second argument, following the gdImagePtr argument. Two such pointers are declared in the provided include files gdfonts.h and gdfontl.h.

gdImage

gdImage is the data structure in which gd stores images. gdImageCreate returns a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. You may read the members sx (size on x-axis), sy (size on y-axis), colorsTotal (total colors), red (red component of colors; an array of 256 integers between 0 and 255), green (green component of colors), blue (blue component of colors), and transparent (index of transparent color; -1 if none).

gdImagePtr

gdImagePtr is a pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdPoint

gdPoint represents a point in the coordinate space of the image. It is used by gdImagePolygon and gdImageFilledPolygon.

gdPointPtr

gdPointPtr is a pointer to a gdPoint structure. It is passed as an argument to gdImagePolygon and gdImageFilledPolygon.

Create, Destroy, and File Functions

The functions for creating, loading, and saving files, unless otherwise noted, return a gdImagePtr to the image being created, loaded, or saved. On failure, a NULL pointer is returned. Failure with these functions most often occurs because the file is corrupt or does not contain a GIF image. The file associated with the image is not closed. All images used by these functions eventually must be destroyed using gdImageDestroy().

gdImageCreate

gdImageCreate is called to create images. You invoke this function with the x and y dimensions of the desired image. Use the following code:

gdImageCreate(sx, sy)

gdImageCreateFromGd

gdImageCreateFromGd is called to load images from gd format files. Invoke this function with an already opened pointer to a file containing the desired image in the gd file format, which is specific to gd and intended for very fast loading. (It is not intended for compression; for compression, use GIF.) You can inspect the sx and sy members of the image to determine its size. Use this code:

gdImageCreateFromGd(FILE *in)

gdImageCreateFromGif

gdImageCreateFromGif is called to load images from GIF format files. You invoke this function with an already opened pointer to a file containing the desired image. You can inspect the sx and sy members of the image to determine its size. Use this code:

gdImageCreateFromGif(FILE *in)

gdImageCreateFromXbm

gdImageCreateFromXbm is called to load images from X bitmap format files. Invoke this function with an already opened pointer to a file containing the desired image. You can inspect the sx and sy members of the image to determine its size. Use this code:

gdImageCreateFromXbm(FILE *in)

gdImageDestroy

gdImageDestroy is used to free the memory associated with an image. It is important to invoke this function before exiting your program or assigning a new image to a gdImagePtr variable. Use this code:

gdImageDestroy(gdImagePtr im)

gdImageGd

gdImageGd outputs the specified image to the specified file in the <A HREF="#gdformat">gd image format. The file must be open for writing. Under MS-DOS, it is important to use "wb" (write binary) as opposed to simply "w" (write) as the mode when opening the file, and under UNIX there is no penalty for doing so. Use this code:

void gdImageGd(gdImagePtr im, FILE *out)

The gdImage format is intended for fast reads and writes of images your program will need frequently to build other images. It is not a compressed format and is not intended for general use.

gdImageGif

gdImageGif outputs the specified image to the specified file in GIF format. The file must be open for writing. Under MS-DOS, it is important to use "wb" (write binary) as opposed to simply "w" (write) as the mode when opening the file, and under UNIX there is no penalty for doing so. Use this code:

void gdImageGif(gdImagePtr im, FILE *out)

gdImageInterlace

gdImageInterlace is used to determine whether an image should be stored in a linear fashion (where lines will appear on the display from first to last) or in an interlaced fashion (where the image will "fade in" over several passes). By default, images are not interlaced. Use this code:

gdImageInterlace(gdImagePtr im, int interlace) (FUncTION)

A nonzero value for the interlace argument turns on interlace; a zero value turns it off. Note that interlace has no effect on other functions and has no meaning unless you save the image in GIF format; the gd and xbm formats do not support interlace.

When a GIF is loaded with gdImageCreateFromGif, interlace is set according to the setting in the GIF file.

Note that many GIF viewers and Web browsers do not support interlace. However, the interlaced GIF still should display; it simply appears all at once, just as other images do.

Drawing Functions

The gdImageFillToBorder and gdImageFill functions are recursive. It is not the most naive implementation possible, and the implementation is expected to improve, but there always will be degenerate cases in which the stack can become very deep. This can be a problem in MS-DOS and Microsoft Windows environments. (Of course, in a UNIX or Windows NT environment with a proper stack, this is not a problem at all.)

gdImageArc

gdImageArc is used to draw a partial ellipse centered at the given point, with the specified width and height in pixels. The arc begins at the position in degrees specified by s and ends at the position specified by e. The arc is drawn in the color specified by the last argument. A circle can be drawn by beginning at 0 degrees and ending at 360 degrees, with width and height being equal. e must be greater than s. Values greater than 360 are interpreted modulo 360. Use this code:

void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e,
  int color)

gdImageDashedLine

gdImageDashedLine is provided solely for backward compatibility with gd 1.0. New programs should draw dashed lines using the normal gdImageLine function and the new gdImageSetStyle function.

gdImageDashedLine is used to draw a dashed line between two endpoints (x1,y1 and x2,y2). The line is drawn using the color index specified. The portions of the line that are not drawn are left transparent so that the background is visible. Use this code:

void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)

gdImageFill

gdImageFill floods a portion of the image with the specified color, beginning at the specified point and flooding the surrounding region of the same color as the starting point. For a way of flooding a region defined by a specific border color rather than by its interior color, see "gdImageFillToBorder."

The fill color can be gdTiled, resulting in a tile fill using another image as the tile. The tile image cannot be transparent, however. If the image you want to fill with has a transparent color index, call gdImageTransparent on the tile image and set the transparent color index to -1 to turn off its transparency. Use this code:

void gdImageFill(gdImagePtr im, int x, int y, int color)

gdImageFilledPolygon

gdImageFilledPolygon is used to fill a polygon with the vertices (at least three) specified, using the color index specified. See also "gdImagePolygon." Use this code:

void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal,
  int color)

gdImageFilledRectangle

gdImageFilledRectangle is used to draw a solid rectangle with the two corners (upper left first, then lower right) specified, using the color index specified. Use this code:

void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2,
  int color)

gdImageFillToBorder

gdImageFillToBorder floods a portion of the image with the specified color, beginning at the specified point and stopping at the specified border color. For a way of flooding an area defined by the color of the starting point, see "gdImageFill."

The border color cannot be a special color such as gdTiled; it must be a proper solid color. The fill color can be gdTiled, however. Use this code:

void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color)

gdImageLine

gdImageLine is used to draw a line between two endpoints (x1,y1 and x2,y2).

The line is drawn using the color index specified. Note that the color index can be an actual color returned by gdImageColorAllocate or one of gdStyled, gdBrushed, or gdStyledBrushed. Use this code:

void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)

gdImagePolygon

gdImagePolygon is used to draw a polygon with the vertices (at least three) specified, using the color index specified. See also "gdImageFilledPolygon." Use this code:

void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal,
  int color)

gdImageRectangle

gdImageRectangle is used to draw a rectangle with the two corners (upper left first, then lower right) specified, using the color index specified. Use this code:

void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)

gdImageSetBrush

A brush is an image used to draw wide, shaped strokes in another image. Just as a paintbrush is not a single point, a brush image does not need to be a single pixel. Any gd image can be used as a brush, and by setting the transparent color index of the brush image with gdImageColorTransparent, a brush of any shape can be created. All line-drawing functions, such as gdImageLine and gdImagePolygon, will use the current brush if the special "color" gdBrushed or gdStyledBrushed is used when calling them.

gdImageSetBrush is used to specify the brush to be used in a particular image. You can set any image to be the brush. If the brush image does not have the same color map as the first image, any colors missing from the first image are allocated. If not enough colors can be allocated, the closest colors already available are used. This allows arbitrary GIFs to be used as brush images. It also means, however, that you should not set a brush unless you actually will use it; if you set a rapid succession of different brush images, you quickly can fill your color map and the results will not be optimal. Use this code:

void gdImageSetBrush(gdImagePtr im, gdImagePtr brush)

You do not need to take any special action when you are finished with a brush. As for any other image, if you will not be using the brush image for any further purpose, you should call gdImageDestroy. You must not use the color gdBrushed if the current brush has been destroyed; you can, of course, set a new brush to replace it.

gdImageSetPixel

gdImageSetPixel sets a pixel to a particular color index. Always use this function or one of the other drawing functions to access pixels; do not access the pixels of the gdImage structure directly. Use this code:

void gdImageSetPixel(gdImagePtr im, int x, int y, int color)

gdImageSetStyle

It is often desirable to draw dashed lines, dotted lines, and other variations on a broken line. gdImageSetStyle can be used to set any desired series of colors, including a special color that leaves the background intact, to be repeated during the drawing of a line.

To use gdImageSetStyle, create an array of integers and assign them the desired series of color values to be repeated. You can assign the special color value gdTransparent to indicate that the existing color should be left unchanged for that particular pixel (allowing a dashed line to be attractively drawn over an existing image). Use this code:

void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)

Then, to draw a line using the style, use the normal gdImageLine function with the special color value gdStyled.

As of version 1.1.1, the style array is copied when you set the style, so you do not need to be concerned with keeping the array around indefinitely. This should not break existing code that assumes that styles are not copied.

You also can combine styles and brushes to draw the brush image at intervals instead of in a continuous stroke. When creating a style for use with a brush, the style values are interpreted differently; 0 indicates pixels at which the brush should not be drawn, whereas 1 indicates pixels at which the brush should be drawn. To draw a styled, brushed line, you must use the special color value gdStyledBrushed. For an example of this feature in use, see gddemo.c (provided in the gd library distribution).

gdImageSetTile

A tile is an image used to fill an area with a repeated pattern. Any gd image can be used as a tile, and by setting the transparent color index of the tile image with gdImageColorTransparent, a tile that allows certain parts of the underlying area to shine through can be created. All region-filling functions, such as gdImageFill and gdImageFilledPolygon, will use the current tile if the special "color" gdTiled is used when calling them.

gdImageSetTile is used to specify the tile to be used in a particular image. You can set any image to be the tile. If the tile image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary GIFs to be used as tile images. It also means, however, that you should not set a tile unless you actually will use it; if you set a rapid succession of different tile images, you quickly can fill your color map and the results will not be optimal. Use this code:

void gdImageSetTile(gdImagePtr im, gdImagePtr tile)

You do not need to take any special action when you are finished with a tile. As for any other image, if you will not be using the tile image for any further purpose, you should call gdImageDestroy. You must not use the color gdTiled if the current tile has been destroyed; you can, of course, set a new tile to replace it.

Query Functions

The query functions set includes a set of macros to use to access the gdImage color structure. Use these macros instead of accessing the color structure members directly. Each macro follows this syntax:

int gdImageColor(gdImagePtr im, int color)

Replace the Color in gdImageColor with Blue, Red, or Green to return the respective color component of the specified color index. Always use the supplied macros to access structures instead of accessing the structures directly.

gdImageBoundsSafe

gdImageBoundsSafe returns true (1) if the specified point is within the bounds of the image and false (0) if it is not. This function is intended primarily for use by those who want to add functions to gd. All the gd drawing functions already clip safely to the edges of the image. Use this code:

int gdImageBoundsSafe(gdImagePtr im, int x, int y)

gdImageGetPixel

gdImageGetPixel retrieves the color index of a particular pixel. Always use this function to query pixels; do not access the pixels of gdImage structure directly. Use this code:

int gdImageGetPixel(gdImagePtr im, int x, int y)

gdImageSX

gdImageSX is a macro that returns the width of the image in pixels. Use this code:

int gdImageSX(gdImagePtr im)

gdImageSY

gdImageSY is a macro that returns the height of the image in pixels. Use this code:

int gdImageSY(gdImagePtr im)

Font and Text-Handling Functions

The following font and text-handling functions have a common parameter list. The fifth argument provides function-specific information. The second argument is a pointer to a font definition structure. Five fonts are provided with gd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, and gdFontGiant. You must include the files gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h, and gdfontg.h, respectively, and (if you are not using a library-based approach) you must link with the corresponding .c files to use the provided fonts. Pixels not set by a particular character retain their previous color.

gdImageChar

gdImageChar is used to draw single characters on the image. The character specified by the fifth argument is drawn from left to right in the specified color. Use this code:

void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y, int c, int color)

gdImageCharUp

gdImageCharUp is used to draw single characters on the image, rotated 90 degrees. The character specified by the fifth argument is drawn from bottom to top, rotated at a 90-degree angle, in the specified color. Use this code:

void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y, int c,
  int color)

gdImageString

gdImageString is used to draw multiple characters on the image. The null-terminated C string specified by the fifth argument is drawn from left to right in the specified color. Use this code:

void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y, char *s,
  int color)

gdImageStringUp

gdImageStringUp is used to draw multiple characters on the image, rotated 90 degrees. The null-terminated C string specified by the fifth argument is drawn from bottom to top (rotated 90 degrees) in the specified color. Use this code:

void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y, char *s,
  int color)

Color-Handling Functions

The macros of the color-handling functions should be used to obtain structure information; do not access the structure directly.

gdImageColorAllocate

gdImageColorAllocate finds the first available color index in the image specified, sets its RGB values to those requested (255 is the maximum for each), and returns the index of the new color table entry. When creating a new image, the first time you invoke this function, you are setting the background color for that image. Use this code:

int gdImageColorAllocate(gdImagePtr im, int r, int g, int b)

In the event that all gdMaxColors colors (256) already have been allocated, gdImageColorAllocate returns -1 to indicate failure. (This is not uncommon when working with existing GIF files that already use 256 colors.)

gdImageColorClosest

gdImageColorClosest searches the colors that have been defined so far in the image specified and returns the index of the color with RGB values closest to those of the request. (Closeness is determined by Euclidean distance, which is used to determine the distance in three-dimensional color space between colors.) Use this code:

int gdImageColorClosest(gdImagePtr im, int r, int g, int b)

If no colors have yet been allocated in the image, gdImageColorClosest returns -1.

This function is most useful as a backup method for choosing a drawing color when an image already contains gdMaxColors (256) colors and no more can be allocated.

gdImageColorDeallocate

gdImageColorDeallocate marks the specified color as being available for reuse. It does not attempt to determine whether the color index is still in use in the image. After a call to this function, the next call to gdImageColorAllocate for the same image sets new RGB values for that color index, changing the color of any pixels that have that index as a result. If multiple calls to gdImageColorDeallocate are made consecutively, the lowest-numbered index among them will be reused by the next gdImageColorAllocate call. Use this code:

void gdImageColorDeallocate(gdImagePtr im, int color)

gdImageColorExact

gdImageColorExact searches the colors that have been defined so far in the image specified and returns the index of the first color with RGB values that exactly match those of the request. If no allocated color matches the request precisely, gdImageColorExact returns -1. Use this code:

int gdImageColorExact(gdImagePtr im, int r, int g, int b)

gdImageColorPortion

gdImageColorPortion is a set of macros to return the Portion of the specified color in the image. Replace Portion with Red, Green, or Blue. Use this code:

int gdImageColorPortion(gdImagePtr im, int c)

gdImageColorsTotal

gdImageColorsTotal is a macro that returns the number of colors currently allocated in the image. Use this code:

int gdImageColorsTotal(gdImagePtr im)

gdImageColorTransparent

gdImageColorTransparent sets the transparent color index for the specified image to the specified index. To indicate that there should be no transparent color, invoke gdImageColorTransparent with a color index of -1.

The color index used should be an index allocated by gdImageColorAllocate, whether explicitly invoked by your code or implicitly invoked by loading an image. In order to ensure that your image has a reasonable appearance when viewed by users who do not have transparent background capabilities, be sure to give reasonable RGB values to the color you allocate for use as a transparent color, even though it will be transparent on systems that support transparency. Use this code:

void gdImageColorTransparent(gdImagePtr im, int color)

gdImageGetInterlaced

gdImageGetInterlaced is a macro that returns true (1) if the image is interlaced and false (0) if it is not. Use this code:

int gdImageGetInterlaced(gdImagePtr im)

gdImageGetTransparent

gdImageGetTransparent is a macro that returns the current transparent color index in the image. If there is no transparent color, gdImageGetTransparent returns -1. Use this code:

int gdImageGetTransparent(gdImagePtr im)

Copying and Resizing Functions

The two copy functions presented in this section have a similar parameter format.

The dst argument is the destination image to which the region will be copied. The src argument is the source image from which the region is copied. The dstX and dstY arguments specify the point in the destination image to which the region will be copied. The srcX and srcY arguments specify the upper left corner of the region in the source image.

When you copy a region from one location in an image to another location in the same image, gdImageCopy performs as expected unless the regions overlap, in which case the result is unpredictable. If this presents a problem, create a scratch image in which to keep intermediate results.

gdImageCopy

gdImageCopy is used to copy a rectangular portion of one image to another image. Use this code:

void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX,
  int srcY, int w, int h)

gdImageCopyResized

gdImageCopyResized is used to copy a rectangular portion of one image to another image. The x and y dimensions of the original region and the destination region can vary, resulting in stretching or shrinking of the region, as appropriate. Use this code:

void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX, int dstY,
  int srcX, int srcY, int destW, int destH, int srcW, int srcH)

The dstW and dstH arguments specify the width and height of the destination region. The srcW and srcH arguments specify the width and height of the source region and can differ from the destination size, allowing a region to be scaled during the copying process.

Summary

In this chapter, you learned how to add access counters to your home page. Along the way, you learned about DBM files, which will help you with all kinds of practical applications. You learned about several access counter summary programs that can make your page-counting tasks much easier. Also in this chapter, you learned how to build bitmaps and how to use them. With this knowledge, you can create your own images any time you want. Besides learning about several nice existing counter programs, you also learned about the gd 1.2 library for generating graphics images on-the-fly. I hope you find the section on gd 1.2 an excellent reference tool that you can return to over and over again.

Q&A

Listing 10.17. An 8¥10 bitmap of 0.

Translate each row into a number by replacing each empty row with a 0 and each checked row with a 1 so the rows in Listing 10.17 convert as shown in Table 10.6.

Each hexadecimal number is made up of 4 bits, so the easiest maps to draw are multiples of 4 wide. The height can be any number that looks good. You can almost see the pattern just in the 1s and 0s themselves. If you don't understand hexadecimal numbering, just get a binary-to-hexadecimal calculator and draw your bitmaps in multiples of 4 wide. Put 1s in the rows you want on and 0s in the rows you want off. Put your calculator in binary mode, put the 1s and 0s on your grid, and then convert them to hexadecimal numbers. You are ready to go. The grid in Listing 10.18 produces the letter E for an 8¥10 bitmapped letter E.

Listing 10.18. An 8¥10 bitmap of the letter E.

Table 10.7 shows the translation for the bitmap.