H2PH(1)

💖 NAME 💖

h2ph — bestie, it converts .h C header files into .ph Perl header files, and honestly? iconic behavior.

So like, this is from the Perl Programmers Reference Guide, section 1, and the whole point of it is turning your crusty old C headers into something Perl can vibe with. 🦋

✨ SYNOPSIS ✨

h2ph [-d destination directory] [-r | -a] [-l] [-h] [-e] [-D] [-Q]
[headerfiles]

🌸 DESCRIPTION 🌸

Okay so h2ph takes any C header files you throw at it and converts them into the corresponding Perl header file format. The easiest way to run it is while you're sitting in /usr/include, like:

cd /usr/include; h2ph * sys/*

or, if you're feeling extra:

cd /usr/include; h2ph * sys/* arpa/* netinet/*

or, the full main-character move:

cd /usr/include; h2ph -r -l .

The output files get dropped into the hierarchy rooted at Perl's architecture dependent library directory. Not vibing with that location? Just say so with a -d switch and pick your own hierarchy, no cap.

And if you run it with no arguments at all, it just filters standard input to standard output. Simple. Clean. A little mysterious. 💅

---

🎀 OPTIONS 🎀

• -d destination_dir — drop the resulting .ph files underneath destination_dir instead of underneath the default Perl library location ($Config{'installsitearch'}). You're the boss of your own filesystem, bestie.
• -r — run recursively! If any of headerfiles are directories, then h2ph gets run on all the files in those directories (and their subdirectories, etc., etc., all the way down 🌀). Heads up: -r and -a are mutually exclusive — they cannot both be your moment.
• -a — run automagically ✨ convert headerfiles, plus any .h files which they include. This one searches for .h files in all the directories your C compiler ordinarily uses. Also, -a and -r are mutually exclusive, so pick a lane.
• -l — symbolic links get replicated in the destination directory. If you don't pass -l, then links are just skipped over. Gone. Ignored. 🙈
• -h — put 'hints' in the .ph files, which helps when you're hunting down problems with h2ph. So in those cases where you genuinely need a .ph file that contains syntax errors, instead of the cryptic

[ some error condition ] at (eval mmm) line nnn

you'll see the slightly more helpful

[ some error condition ] at filename.ph line nnn

Gorgeous, right? Only catch: the .ph files almost double in size when you build them with -h. Worth it for the clarity though, imo.

• -e — if an error pops up during conversion, the output file gets removed and a warning gets emitted instead of the whole conversion terminating immediately. Graceful failure, we love to see it. 🫶
• -D — include the code from the .h file as a comment inside the .ph file. This is primarily used for debugging h2ph itself. Detective mode. 🔍
• -Q — 'Quiet' mode 🧚 don't print out the names of the files being converted. Sometimes silence really is the vibe.

👑 ENVIRONMENT 👑

No environment variables are used. Literally none. Zero. Nada. The env is not the main character here. 💀

🌈 FILES 🌈

 /usr/include/*.h
 /usr/include/sys/*.h

etc. (you get the picture, bestie).

⭐ AUTHOR ⭐

Larry Wall. The icon. The legend. 👑

🔥 SEE ALSO 🔥

• perl(1)

💜 DIAGNOSTICS 💜

The usual warnings if it can't read or write the files involved. Like, standard stuff — nothing dramatic, just the classic "can't touch this file" energy.

🍓 BUGS 🍓

Okay, deep breath, because there are a few things you should know, fr fr:

• It doesn't construct the %sizeof array for you. You're on your own for that one, bestie. 😭
• It doesn't handle all C constructs, but it does attempt to isolate definitions inside evals so that you can still get at the definitions that it can translate. Partial credit, slay.
• It's only intended as a rough tool. You may need to dicker with the files produced. Yes, dicker. That's the word. You'll be fiddling with these files, ngl.
• You have to run this program by hand — it's not run as part of the Perl installation. So it's not automatic, it's a whole manual thing. 🙈
• It doesn't handle complicated expressions built piecemeal, a la:

enum {
    FIRST_VALUE,
    SECOND_VALUE,
#ifdef ABC
    THIRD_VALUE
#endif
};

• It doesn't necessarily locate all of your C compiler's internally-defined symbols. Some of them are just gonna be out there, living their truth, unlocated.

---

Fair warning bestie: this is a rough tool by design, so don't expect perfection — dicker with the output and you'll be fine. 💖

---

Okay that's the whole page, mwah! This gorgeous little manual dropped as perl v5.42.3, dated 2026-11-03 — go forth and convert those headers, bestie 🎀✨