1C2PH(1)                Perl Programmers Reference Guide                C2PH(1)
2
3
4

NAME

6       c2ph, pstruct - Dump C structures as generated from "cc -g -S" stabs
7

SYNOPSIS

9           c2ph [-dpnP] [var=val] [files ...]
10
11   OPTIONS
12           Options:
13
14           -w  wide; short for: type_width=45 member_width=35 offset_width=8
15           -x  hex; short for:  offset_fmt=x offset_width=08 size_fmt=x size_width=04
16
17           -n  do not generate perl code  (default when invoked as pstruct)
18           -p  generate perl code         (default when invoked as c2ph)
19           -v  generate perl code, with C decls as comments
20
21           -i  do NOT recompute sizes for intrinsic datatypes
22           -a  dump information on intrinsics also
23
24           -t  trace execution
25           -d  spew reams of debugging output
26
27           -slist  give comma-separated list a structures to dump
28

DESCRIPTION

30       The following is the old c2ph.doc documentation by Tom Christiansen
31       <tchrist@perl.com> Date: 25 Jul 91 08:10:21 GMT
32
33       Once upon a time, I wrote a program called pstruct.  It was a perl
34       program that tried to parse out C structures and display their member
35       offsets for you.  This was especially useful for people looking at
36       binary dumps or poking around the kernel.
37
38       Pstruct was not a pretty program.  Neither was it particularly robust.
39       The problem, you see, was that the C compiler was much better at
40       parsing C than I could ever hope to be.
41
42       So I got smart:  I decided to be lazy and let the C compiler parse the
43       C, which would spit out debugger stabs for me to read.  These were much
44       easier to parse.  It's still not a pretty program, but at least it's
45       more robust.
46
47       Pstruct takes any .c or .h files, or preferably .s ones, since that's
48       the format it is going to massage them into anyway, and spits out
49       listings like this:
50
51        struct tty {
52          int                          tty.t_locker                         000      4
53          int                          tty.t_mutex_index                    004      4
54          struct tty *                 tty.t_tp_virt                        008      4
55          struct clist                 tty.t_rawq                           00c     20
56            int                        tty.t_rawq.c_cc                      00c      4
57            int                        tty.t_rawq.c_cmax                    010      4
58            int                        tty.t_rawq.c_cfx                     014      4
59            int                        tty.t_rawq.c_clx                     018      4
60            struct tty *               tty.t_rawq.c_tp_cpu                  01c      4
61            struct tty *               tty.t_rawq.c_tp_iop                  020      4
62            unsigned char *            tty.t_rawq.c_buf_cpu                 024      4
63            unsigned char *            tty.t_rawq.c_buf_iop                 028      4
64          struct clist                 tty.t_canq                           02c     20
65            int                        tty.t_canq.c_cc                      02c      4
66            int                        tty.t_canq.c_cmax                    030      4
67            int                        tty.t_canq.c_cfx                     034      4
68            int                        tty.t_canq.c_clx                     038      4
69            struct tty *               tty.t_canq.c_tp_cpu                  03c      4
70            struct tty *               tty.t_canq.c_tp_iop                  040      4
71            unsigned char *            tty.t_canq.c_buf_cpu                 044      4
72            unsigned char *            tty.t_canq.c_buf_iop                 048      4
73          struct clist                 tty.t_outq                           04c     20
74            int                        tty.t_outq.c_cc                      04c      4
75            int                        tty.t_outq.c_cmax                    050      4
76            int                        tty.t_outq.c_cfx                     054      4
77            int                        tty.t_outq.c_clx                     058      4
78            struct tty *               tty.t_outq.c_tp_cpu                  05c      4
79            struct tty *               tty.t_outq.c_tp_iop                  060      4
80            unsigned char *            tty.t_outq.c_buf_cpu                 064      4
81            unsigned char *            tty.t_outq.c_buf_iop                 068      4
82          (*int)()                     tty.t_oproc_cpu                      06c      4
83          (*int)()                     tty.t_oproc_iop                      070      4
84          (*int)()                     tty.t_stopproc_cpu                   074      4
85          (*int)()                     tty.t_stopproc_iop                   078      4
86          struct thread *              tty.t_rsel                           07c      4
87
88       etc.
89
90       Actually, this was generated by a particular set of options.  You can
91       control the formatting of each column, whether you prefer wide or fat,
92       hex or decimal, leading zeroes or whatever.
93
94       All you need to be able to use this is a C compiler than generates
95       BSD/GCC-style stabs.  The -g option on native BSD compilers and GCC
96       should get this for you.
97
98       To learn more, just type a bogus option, like -\?, and a long usage
99       message will be provided.  There are a fair number of possibilities.
100
101       If you're only a C programmer, than this is the end of the message for
102       you.  You can quit right now, and if you care to, save off the source
103       and run it when you feel like it.  Or not.
104
105       But if you're a perl programmer, then for you I have something much
106       more wondrous than just a structure offset printer.
107
108       You see, if you call pstruct by its other incybernation, c2ph, you have
109       a code generator that translates C code into perl code!  Well,
110       structure and union declarations at least, but that's quite a bit.
111
112       Prior to this point, anyone programming in perl who wanted to interact
113       with C programs, like the kernel, was forced to guess the layouts of
114       the C structures, and then hardwire these into his program.  Of course,
115       when you took your wonderfully crafted program to a system where the
116       sgtty structure was laid out differently, your program broke.  Which is
117       a shame.
118
119       We've had Larry's h2ph translator, which helped, but that only works on
120       cpp symbols, not real C, which was also very much needed.  What I offer
121       you is a symbolic way of getting at all the C structures.  I've couched
122       them in terms of packages and functions.  Consider the following
123       program:
124
125           #!/usr/local/bin/perl
126
127           require 'syscall.ph';
128           require 'sys/time.ph';
129           require 'sys/resource.ph';
130
131           $ru = "\0" x &rusage'sizeof();
132
133           syscall(&SYS_getrusage, &RUSAGE_SELF, $ru)      && die "getrusage: $!";
134
135           @ru = unpack($t = &rusage'typedef(), $ru);
136
137           $utime =  $ru[ &rusage'ru_utime + &timeval'tv_sec  ]
138                  + ($ru[ &rusage'ru_utime + &timeval'tv_usec ]) / 1e6;
139
140           $stime =  $ru[ &rusage'ru_stime + &timeval'tv_sec  ]
141                  + ($ru[ &rusage'ru_stime + &timeval'tv_usec ]) / 1e6;
142
143           printf "you have used %8.3fs+%8.3fu seconds.\n", $utime, $stime;
144
145       As you see, the name of the package is the name of the structure.
146       Regular fields are just their own names.  Plus the following accessor
147       functions are provided for your convenience:
148
149           struct      This takes no arguments, and is merely the number of first-level
150                       elements in the structure.  You would use this for indexing
151                       into arrays of structures, perhaps like this
152
153
154                           $usec = $u[ &user'u_utimer
155                                       + (&ITIMER_VIRTUAL * &itimerval'struct)
156                                       + &itimerval'it_value
157                                       + &timeval'tv_usec
158                                     ];
159
160           sizeof      Returns the bytes in the structure, or the member if
161                       you pass it an argument, such as
162
163                               &rusage'sizeof(&rusage'ru_utime)
164
165           typedef     This is the perl format definition for passing to pack and
166                       unpack.  If you ask for the typedef of a nothing, you get
167                       the whole structure, otherwise you get that of the member
168                       you ask for.  Padding is taken care of, as is the magic to
169                       guarantee that a union is unpacked into all its aliases.
170                       Bitfields are not quite yet supported however.
171
172           offsetof    This function is the byte offset into the array of that
173                       member.  You may wish to use this for indexing directly
174                       into the packed structure with vec() if you're too lazy
175                       to unpack it.
176
177           typeof      Not to be confused with the typedef accessor function, this
178                       one returns the C type of that field.  This would allow
179                       you to print out a nice structured pretty print of some
180                       structure without knoning anything about it beforehand.
181                       No args to this one is a noop.  Someday I'll post such
182                       a thing to dump out your u structure for you.
183
184       The way I see this being used is like basically this:
185
186               % h2ph <some_include_file.h  >  /usr/lib/perl/tmp.ph
187               % c2ph  some_include_file.h  >> /usr/lib/perl/tmp.ph
188               % install
189
190       It's a little tricker with c2ph because you have to get the includes
191       right.  I can't know this for your system, but it's not usually too
192       terribly difficult.
193
194       The code isn't pretty as I mentioned  -- I never thought it would be a
195       1000- line program when I started, or I might not have begun. :-)  But
196       I would have been less cavalier in how the parts of the program
197       communicated with each other, etc.  It might also have helped if I
198       didn't have to divine the makeup of the stabs on the fly, and then
199       account for micro differences between my compiler and gcc.
200
201       Anyway, here it is.  Should run on perl v4 or greater.  Maybe less.
202
203        --tom
204
205
206
207perl v5.12.4                      2011-11-04                           C2PH(1)
Impressum