H2PH(1perl)

💖 H2PH — the manual, but make it make sense

okay bestie, gather round, because today we're talking about h2ph, the little utility that lives in the Perl Programmers Reference Guide and does exactly one job: it takes your .h C header files and turns them into .ph Perl header files. that's the whole vibe. it's giving translator, it's giving glow-up, it's giving "i speak both languages actually". 🦋

---

✨ NAME ✨

h2ph — convert .h C header files to .ph Perl header files 💅

---

✨ SYNOPSIS ✨

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

---

✨ DESCRIPTION ✨

so here's the tea: h2ph converts any C header files you hand it into the corresponding Perl header file format. iconic behavior. honestly?

the easiest way to run it is from inside /usr/include, like:

cd /usr/include; h2ph * sys/*

or, if you want more:

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

or, the full send:

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

the output files get dropped into the hierarchy rooted at Perl's architecture dependent library directory — that's its home, that's where it lives, that's its main character address. 🏠 but if you want a different hierarchy, you just say so with the -d switch. slay, options, we love her.

and if you run it with no arguments at all? it just filters standard input to standard output. no notes. a pipe queen. 🎀

---

✨ OPTIONS ✨

• -d destination_dir — put the resulting .ph files beneath destination_dir instead of beneath the default Perl library location ($Config{'installsitearch'}). moving out, getting a new place, very that. 💜
• -r — run recursively. if any of headerfiles are directories, then run h2ph on all files in those directories (and their subdirectories, etc. — down and down and down, it's giving inception). 🌀 heads up: -r and -a are mutually exclusive, so you literally cannot have both, pick a lane bestie.
• -a — run automagically ✨. convert headerfiles, as well as any .h files which they include. this option will search for .h files in all directories which your C compiler ordinarily uses. no cap, all of them. and yes: -a and -r are mutually exclusive, same deal as above. 🙅
• -l — symbolic links will be replicated in the destination directory. if -l is not specified, then links are skipped over. so either you bring the links with you or you leave them at the door. 🚪
• -h — put 'hints' in the .ph files which will help in locating problems with h2ph. so in those cases when you require a .ph file containing syntax errors, instead of the cryptic

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

you will see the slightly more helpful

[ some error condition ] at filename.ph line nnn

like… actual information?? we love clarity. but plot twist: the .ph files almost double in size when built using -h. 💀 so it's helpful and heavy, choose wisely.

• -e — if an error is encountered during conversion, the output file will be removed and a warning emitted, instead of terminating the conversion immediately. so it keeps going, it doesn't crash out, it just quietly cleans up after itself. resilient queen. 😭
• -D — include the code from the .h file as a comment in the .ph file. this is primarily used for debugging h2ph. receipts, in the file, for later. 🔍
• -Q — 'Quiet' mode; don't print out the names of the files being converted. sometimes you just don't need to announce every single thing you're doing. mysterious. 🤫

---

✨ ENVIRONMENT ✨

literally none. no environment variables are used. nothing to configure, nothing to export, nothing to stress about. a clean slate, a fresh face. 🌸

---

✨ FILES ✨

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

etc. — and by "etc." we mean etc., there's more, that's the point. 🫶

---

✨ AUTHOR ✨

Larry Wall 👑 — yes, that Larry Wall. the legend himself.

---

✨ SEE ALSO ✨

perl(1) — go read it, bestie, it's the whole universe this little tool lives inside. 🌈

---

✨ DIAGNOSTICS ✨

the usual warnings if it can't read or write the files involved. nothing dramatic, nothing mysterious — if it can't touch the file, it's gonna tell you about it. 📢

---

✨ BUGS ✨

okay so this is the part where we're honest. ✋

• doesn't construct the %sizeof array for you. not its job, apparently. 🙈
• it doesn't handle all C constructs, but it does attempt to isolate definitions inside evals so that you can get at the definitions that it can translate. so like, partial credit, but the effort is genuinely there. 💪
• it's only intended as a rough tool. you may need to dicker with the files produced. yes, dicker. as in poke at them, adjust them, have a whole conversation with them. 🔧
• you have to run this program by hand; it's not run as part of the Perl installation. no automation, no cron goblin doing it for you. you, personally, with your own two hands. 😭
• doesn't handle complicated expressions built piecemeal, a la:

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

like… it said no to that specific situation. 🚫

• doesn't necessarily locate all of your C compiler's internally-defined symbols. some of them are just out here living their truth, unfound. 🔍💀

---

and that's the whole page, bestie. this documentation came from the Perl Programmers Reference Guide, straight out of perl v5.44.0, dated 2026-10-17. take care of her, run her from the right directory, and always read the BUGS section before you get mad at a tool. mwah. 💖✨🎀