Simple Arguments and Return Values

One thing that C is good at is bit handling. In this section, you create a set of functions to handle a bit array. For simplicity, make it a fixed size (16×16).

You’ll need two C functions, one to set a bit to a given value and the other to return the value of the bit. Listing 14.2 contains the functions along with a little Perl code to test it.

Listing 14.2. bits1.pl

use strict; 
use warnings; 

use Inline "C";   
sub set_bit($$$); 
sub test_bit($$); 

set_bit(1,1,1); 
set_bit(1,2,1); 
if ((test_bit(1,1) != 1) || 
    (test_bit(1,2) != 1) || 
    (test_bit(1,3) != 0)) {
    die("Test #1 Failed"); 
} 

set_bit(1,1,0); 

if (test_bit(1,1) != 0) {
    die("Test #2 Failed"); 
} 
print "Successed!
"; 
__END__ 
__C__ 

#define X_SIZE 16 
#define Y_SIZE 16 
static int array[X_SIZE/8][Y_SIZE]; 

void set_bit(int x, int y, int value) {
    if (value != 0) 
        array[x/8][y] |= (0x80 >> (x % 8)); 
    else 
        array[x/8][y] &= ~(0x80 >> (x % 8)); 
} 

int test_bit(int x, int y) 
{
    return ((array[x/8][y] & (0x80 >> (x % 8))) != 0); 
}

At this point, the most important part of the code is what you didn’t write. You didn’t have to take care of all the data conversions between Perl’s internal scalar types and the function parameters. All that work was done behind the scenes by Inline.

Dealing with Trouble

Unfortunately, no one is perfect. From time to time, you’ll make a mistake and your program won’t compile. When that happens you’ll get an error message such as this:

A problem was encountered while attempting to compile and install your Inline 
C code. The command that failed was: 
  make > out.make 2>&1 

The build directory was: 
/home/oualline/bits/_Inline/build/bits1_pl_51cd 

To debug the problem, cd to the build directory, 
and inspect the output files. 

 at bits1.pl line 0 
INIT failed––call queue aborted.

The directory, _Inline/build/..... (UNIX systems), contains the intermediate files that Inline created behind the scenes. Because your program wouldn’t compile, the module decided to save its work so that you can use it to figure out what happened.

Table 14.1 provides the typical elements of a build directory and a brief description of each.

The out.make file contains the output of the compilation. Any error messages will be stored here. The other significant file is the .xs file. It contains a version of your inline code, which is compiled by the Perl utility xsubpp into C code, which is then compiled into a local module. If there is a problem with your C code, the errors will refer to a line in this file.

The xs format combines C code with information about it so that Perl can use the C functions provided. The format of this file is documented in the online document perldoc perlxs. You don’t have to worry about the format of this file because the Inline module takes care of creating it for you.