Debian Codegraph @

upstream/opensuse-tumbleweed/man1/h2ph.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "H2PH 1"
61 .TH H2PH 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 h2ph \- convert .h C header files to .ph Perl header files
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBh2ph [\-d destination directory] [\-r | \-a] [\-l] [\-h] [\-e] [\-D] [\-Q]
71 [headerfiles]\fR
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 \&\fIh2ph\fR
75 converts any C header files specified to the corresponding Perl header file
76 format.
77 It is most easily run while in /usr/include:
78 .PP
79 .Vb 1
80 \& cd /usr/include; h2ph * sys/*
81 .Ve
82 .PP
83 or
84 .PP
85 .Vb 1
86 \& cd /usr/include; h2ph * sys/* arpa/* netinet/*
87 .Ve
88 .PP
89 or
90 .PP
91 .Vb 1
92 \& cd /usr/include; h2ph \-r \-l .
93 .Ve
94 .PP
95 The output files are placed in the hierarchy rooted at Perl\*(Aqs
96 architecture dependent library directory. You can specify a different
97 hierarchy with a \fB\-d\fR switch.
98 .PP
99 If run with no arguments, filters standard input to standard output.
100 .SH OPTIONS
101 .IX Header "OPTIONS"
102 .IP "\-d destination_dir" 4
103 .IX Item "-d destination_dir"
104 Put the resulting \fB.ph\fR files beneath \fBdestination_dir\fR, instead of
105 beneath the default Perl library location (\f(CW$Config{\*(Aqinstallsitearch\*(Aq}\fR).
106 .IP \-r 4
107 .IX Item "-r"
108 Run recursively; if any of \fBheaderfiles\fR are directories, then run \fIh2ph\fR
109 on all files in those directories (and their subdirectories, etc.). \fB\-r\fR
110 and \fB\-a\fR are mutually exclusive.
111 .IP \-a 4
112 .IX Item "-a"
113 Run automagically; convert \fBheaderfiles\fR, as well as any \fB.h\fR files
114 which they include. This option will search for \fB.h\fR files in all
115 directories which your C compiler ordinarily uses. \fB\-a\fR and \fB\-r\fR are
116 mutually exclusive.
117 .IP \-l 4
118 .IX Item "-l"
119 Symbolic links will be replicated in the destination directory. If \fB\-l\fR
120 is not specified, then links are skipped over.
121 .IP \-h 4
122 .IX Item "-h"
123 Put \*(Aqhints\*(Aq in the .ph files which will help in locating problems with
124 \&\fIh2ph\fR. In those cases when you \fBrequire\fR a \fB.ph\fR file containing syntax
125 errors, instead of the cryptic
126 .Sp
127 .Vb 1
128 \& [ some error condition ] at (eval mmm) line nnn
129 .Ve
130 .Sp
131 you will see the slightly more helpful
132 .Sp
133 .Vb 1
134 \& [ some error condition ] at filename.ph line nnn
135 .Ve
136 .Sp
137 However, the \fB.ph\fR files almost double in size when built using \fB\-h\fR.
138 .IP \-e 4
139 .IX Item "-e"
140 If an error is encountered during conversion, output file will be removed and
141 a warning emitted instead of terminating the conversion immediately.
142 .IP \-D 4
143 .IX Item "-D"
144 Include the code from the \fB.h\fR file as a comment in the \fB.ph\fR file.
145 This is primarily used for debugging \fIh2ph\fR.
146 .IP \-Q 4
147 .IX Item "-Q"
148 \&\*(AqQuiet\*(Aq mode; don\*(Aqt print out the names of the files being converted.
149 .SH ENVIRONMENT
150 .IX Header "ENVIRONMENT"
151 No environment variables are used.
152 .SH FILES
153 .IX Header "FILES"
154 .Vb 2
155 \& /usr/include/*.h
156 \& /usr/include/sys/*.h
157 .Ve
158 .PP
159 etc.
160 .SH AUTHOR
161 .IX Header "AUTHOR"
162 Larry Wall
163 .SH "SEE ALSO"
164 .IX Header "SEE ALSO"
165 \&\fBperl\fR\|(1)
166 .SH DIAGNOSTICS
167 .IX Header "DIAGNOSTICS"
168 The usual warnings if it can\*(Aqt read or write the files involved.
169 .SH BUGS
170 .IX Header "BUGS"
171 Doesn\*(Aqt construct the \f(CW%sizeof\fR array for you.
172 .PP
173 It doesn\*(Aqt handle all C constructs, but it does attempt to isolate
174 definitions inside evals so that you can get at the definitions
175 that it can translate.
176 .PP
177 It\*(Aqs only intended as a rough tool.
178 You may need to dicker with the files produced.
179 .PP
180 You have to run this program by hand; it\*(Aqs not run as part of the Perl
181 installation.
182 .PP
183 Doesn\*(Aqt handle complicated expressions built piecemeal, a la:
184 .PP
185 .Vb 7
186 \& enum {
187 \& FIRST_VALUE,
188 \& SECOND_VALUE,
189 \& #ifdef ABC
190 \& THIRD_VALUE
191 \& #endif
192 \& };
193 .Ve
194 .PP
195 Doesn\*(Aqt necessarily locate all of your C compiler\*(Aqs internally\-defined
196 symbols.