Perl Cookbook

Using h2ph to Translate C #include Files

Problem

Someone gave you code that generates the bizarre error message:

               
                  Can't locate sys/syscall.ph in @INC (did you run h2ph?)
               
                  (@INC contains: /usr/lib/perl5/i686-linux/5.00404 /usr/lib/perl5
               
                  /usr/lib/perl5/site_perl/i686-linux /usr/lib/perl5/site_perl .)
               
                  at some_program line 7.

You want to know what it means and how to fix it.

Solution

Get your system administrator to do this, running as the superuser:

% cd /usr/include; h2ph sys/syscall.h

However, most include files require other include files, which means you should probably just translate them all:

% cd /usr/include; h2ph *.h */*.h

If that reports too many filenames or misses some that are more deeply nested, try this instead:

% cd /usr/include; find . -name '*.h' -print | xargs h2ph

Discussion

A file whose name ends in ".ph" has been created by the h2ph tool, which translates C preprocessor directives from C #include files into Perl. The goal is to allow Perl code to access the same constants as C code. The h2xs tool is a better approach in most cases because it provides compiled C code for your modules, not Perl code simulating C code. However, using h2xs requires a lot more programming savvy (at least, for accessing C code) than h2ph does.

When h2ph’s translation process works, it’s wonderful. When it doesn’t, you’re probably out of luck. As system architectures and include files become more complex, h2ph fails more frequently. If you’re lucky, the constants you need are already in the Fcntl, ...