h2ph

h2ph [-d <dir>] [-r] [-l] [-D] [-v] [filenames...]

-d <dir>
    Specifies the output directory where the generated Perl header files will be placed. If not specified, it defaults to $(installsitelib)/auto (a Perl installation-specific directory).

-r
    Enables recursive processing of directories. If a directory is provided as input, h2ph will process all C header files found within that directory and its subdirectories.

-l
    When used in conjunction with -r, this option instructs h2ph to follow symbolic links encountered during recursive directory traversal.

-D
    Activates debug mode. In this mode, h2ph will dump the raw output from the underlying C preprocessor (cpp) to standard output, which can be useful for troubleshooting parsing issues.

-v
    Enables verbose mode, causing h2ph to display progress information and details about the files being processed during the conversion.

h2ph is a utility designed to translate C header files (typically those with a .h extension) into corresponding Perl header files (with a .ph extension). Its primary function is to enable Perl scripts to access and utilize values from C preprocessor macros and enum declarations defined within C headers. The command attempts to parse these C constructs, often by leveraging the C preprocessor (cpp) to resolve macro values, and then generates equivalent Perl code. While it can process individual files, h2ph also supports recursive conversion of entire directory trees, making it suitable for processing standard system header directories like /usr/include. The resulting .ph files can then be required by Perl scripts, providing a means to use C constants and definitions within Perl.

h2ph has several known limitations. It may not reliably parse all complex C preprocessor constructs, especially intricate macros or function-like macros, which can lead to incomplete or incorrect translations. Its functionality is heavily dependent on the correct operation and availability of the system's C preprocessor (cpp). Furthermore, the generated Perl header files may sometimes require manual inspection or cleanup to ensure proper functionality or adherence to modern Perl coding practices.

For contemporary Perl development and interfacing with C code, more robust and flexible utilities like ExtUtils::ParseXS or Inline::C are generally preferred, as h2ph represents an older approach primarily used for accessing system call constants via require 'sys/syscall.ph' type calls.

If no specific filenames are provided on the command line, h2ph defaults to searching for C header files in standard system include paths. This typically involves directories like /usr/include and its subdirectories (or other system-specific locations defined by the build environment). It will then attempt to process these found files, generating corresponding Perl header files based on their content.

h2ph is an older utility, primarily associated with earlier versions of Perl. Its initial purpose was to facilitate accessing system-specific constants (such as system call numbers or library constants) defined within C header files. This allowed Perl scripts to utilize these values through simple require statements, like require 'sys/syscall.ph'. While it served a crucial role in enabling early Perl-C integration, its design reflects a time before more sophisticated C interface tools, such as ExtUtils::ParseXS and Inline::C, became prevalent. As these newer, more robust methods for C interoperability in Perl have emerged, the direct usage of h2ph has diminished.

cpp(1), perl(1), ExtUtils::ParseXS(3pm), Inline::C(3pm)