1PIDL(1)               User Contributed Perl Documentation              PIDL(1)
2
3
4

NAME

6       pidl - An IDL compiler written in Perl
7

SYNOPSIS

9       pidl --help
10
11       pidl [--outputdir[=OUTNAME]] [--includedir DIR...] [--parse-idl-tree]
12       [--dump-idl-tree] [--dump-ndr-tree] [--header[=OUTPUT]]
13       [--python[=OUTPUT]] [--ndr-parser[=OUTPUT]] [--client] [--server]
14       [--warn-compat] [--quiet] [--verbose] [--template]
15       [--ws-parser[=OUTPUT]] [--diff] [--dump-idl] [--tdr-parser[=OUTPUT]]
16       [--samba3-ndr-client[=OUTPUT]] [--samba3-ndr-server[=OUTPUT]]
17       [--typelib=[OUTPUT]] [<idlfile>.idl]...
18

DESCRIPTION

20       pidl is an IDL compiler written in Perl that aims to be somewhat
21       compatible with the midl compiler. IDL is short for "Interface
22       Definition Language".
23
24       pidl can generate stubs for DCE/RPC server code, DCE/RPC client code
25       and Wireshark dissectors for DCE/RPC traffic.
26
27       IDL compilers like pidl take a description of an interface as their
28       input and use it to generate C (though support for other languages may
29       be added later) code that can use these interfaces, pretty print data
30       sent using these interfaces, or even generate Wireshark dissectors that
31       can parse data sent over the wire by these interfaces.
32
33       pidl takes IDL files in the same format as is used by midl, converts it
34       to a .pidl file (which contains pidl's internal representation of the
35       interface) and can then generate whatever output you need.  .pidl files
36       should be used for debugging purposes only. Write your interface
37       definitions in .idl format.
38
39       The goal of pidl is to implement a IDL compiler that can be used while
40       developing the RPC subsystem in Samba (for both
41       marshalling/unmarshalling and debugging purposes).
42

OPTIONS

44       --help
45           Show list of available options.
46
47       --version
48           Show pidl version
49
50       --outputdir OUTNAME
51           Write output files to the specified directory.  Defaults to the
52           current directory.
53
54       --includedir DIR
55           Add DIR to the search path used by the preprocessor. This option
56           can be specified multiple times.
57
58       --parse-idl-tree
59           Read internal tree structure from input files rather than assuming
60           they contain IDL.
61
62       --dump-idl
63           Generate a new IDL file. File will be named OUTNAME.idl.
64
65       --header
66           Generate a C header file for the specified interface. Filename
67           defaults to OUTNAME.h.
68
69       --ndr-parser
70           Generate a C file and C header containing NDR parsers. The filename
71           for the parser defaults to ndr_OUTNAME.c. The header filename will
72           be the parser filename with the extension changed from .c to .h.
73
74       --tdr-parser
75           Generate a C file and C header containing TDR parsers. The filename
76           for the parser defaults to tdr_OUTNAME.c. The header filename will
77           be the parser filename with the extension changed from .c to .h.
78
79       --typelib
80           Write type information to the specified file.
81
82       --server
83           Generate boilerplate for the RPC server that implements the
84           interface. Filename defaults to ndr_OUTNAME_s.c.
85
86       --template
87           Generate stubs for a RPC server that implements the interface.
88           Output will be written to stdout.
89
90       --ws-parser
91           Generate an Wireshark dissector (in C) and header file. The
92           dissector filename defaults to packet-dcerpc-OUTNAME.c while the
93           header filename defaults to packet-dcerpc-OUTNAME.h.
94
95           Pidl will read additional data from an Wireshark conformance file
96           if present.  Such a file should have the same location as the IDL
97           file but with the extension cnf rather than idl. See
98           Parse::Pidl::Wireshark::Conformance for details on the format of
99           this file.
100
101       --diff
102           Parse an IDL file,  generate a new IDL file based on the internal
103           data structures and see if there are any differences with the
104           original IDL file.  Useful for debugging pidl.
105
106       --dump-idl-tree
107           Tell pidl to dump the internal tree representation of an IDL file
108           the to disk. Useful for debugging pidl.
109
110       --dump-ndr-tree
111           Tell pidl to dump the internal NDR information tree it generated
112           from the IDL file to disk.  Useful for debugging pidl.
113
114       --samba3-ndr-client
115           Generate client calls for Samba3, to be placed in rpc_client/.
116           Instead of calling out to the code in Samba3's rpc_parse/, this
117           will call out to Samba4's NDR code instead.
118
119       --samba3-ndr-server
120           Generate server calls for Samba3, to be placed in rpc_server/.
121           Instead of calling out to the code in Samba3's rpc_parse/, this
122           will call out to Samba4's NDR code instead.
123

IDL SYNTAX

125       IDL files are always preprocessed using the C preprocessor.
126
127       Pretty much everything in an interface (the interface itself,
128       functions, parameters) can have attributes (or properties whatever name
129       you give them).  Attributes always prepend the element they apply to
130       and are surrounded by square brackets ([]). Multiple attributes are
131       separated by comma's; arguments to attributes are specified between
132       parentheses.
133
134       See the section COMPATIBILITY for the list of attributes that pidl
135       supports.
136
137       C-style comments can be used.
138
139   CONFORMANT ARRAYS
140       A conformant array is one with that ends in [*] or []. The strange
141       things about conformant arrays are that they can only appear as the
142       last element of a structure (unless there is a pointer to the
143       conformant array, of course) and the array size appears before the
144       structure itself on the wire.
145
146       So, in this example:
147
148               typedef struct {
149                       long abc;
150                       long count;
151                       long foo;
152                       [size_is(count)] long s[*];
153               } Struct1;
154
155       it appears like this:
156
157               [size_is] [abc] [count] [foo] [s...]
158
159       the first [size_is] field is the allocation size of the array, and
160       occurs before the array elements and even before the structure
161       alignment.
162
163       Note that size_is() can refer to a constant, but that doesn't change
164       the wire representation. It does not make the array a fixed array.
165
166       midl.exe would write the above array as the following C header:
167
168          typedef struct {
169                       long abc;
170                       long count;
171                       long foo;
172                       long s[1];
173               } Struct1;
174
175       pidl takes a different approach, and writes it like this:
176
177               typedef struct {
178                       long abc;
179                       long count;
180                       long foo;
181                       long *s;
182               } Struct1;
183
184   VARYING ARRAYS
185       A varying array looks like this:
186
187               typedef struct {
188                       long abc;
189                       long count;
190                       long foo;
191                       [size_is(count)] long *s;
192               } Struct1;
193
194       This will look like this on the wire:
195
196               [abc] [count] [foo] [PTR_s]    [count] [s...]
197
198   FIXED ARRAYS
199       A fixed array looks like this:
200
201               typedef struct {
202                       long s[10];
203               } Struct1;
204
205       The NDR representation looks just like 10 separate long declarations.
206       The array size is not encoded on the wire.
207
208       pidl also supports "inline" arrays, which are not part of the IDL/NDR
209       standard. These are declared like this:
210
211               typedef struct {
212                       uint32 foo;
213                       uint32 count;
214                       uint32 bar;
215                       long s[count];
216               } Struct1;
217
218       This appears like this:
219
220               [foo] [count] [bar] [s...]
221
222       Fixed arrays are an extension added to support some of the strange
223       embedded structures in security descriptors and spoolss.
224
225       This section is by no means complete. See the OpenGroup and MSDN
226            documentation for additional information.
227

COMPATIBILITY WITH MIDL

229   Missing features in pidl
230       The following MIDL features are not (yet) implemented in pidl or are
231       implemented with an incompatible interface:
232
233       •   Asynchronous communication
234
235       •   Typelibs (.tlb files)
236
237       •   Datagram support (ncadg_*)
238
239   Supported attributes and statements
240       in, out, ref, length_is, switch_is, size_is, uuid, case, default,
241       string, unique, ptr, pointer_default, v1_enum, object, helpstring,
242       range, local, call_as, endpoint, switch_type, progid, coclass, iid_is,
243       represent_as, transmit_as, import, include, cpp_quote.
244
245   PIDL Specific properties
246       public
247           The [public] property on a structure or union is a pidl extension
248           that forces the generated pull/push functions to be non-static.
249           This allows you to declare types that can be used between modules.
250           If you don't specify [public] then pull/push functions for other
251           than top-level functions are declared static.
252
253       noprint
254           The [noprint] property is a pidl extension that allows you to
255           specify that pidl should not generate a ndr_print_*() function for
256           that structure or union. This is used when you wish to define your
257           own print function that prints a structure in a nicer manner. A
258           good example is the use of [noprint] on dom_sid, which allows the
259           pretty-printing of SIDs.
260
261       value
262           The [value(expression)] property is a pidl extension that allows
263           you to specify the value of a field when it is put on the wire.
264           This allows fields that always have a well-known value to be
265           automatically filled in, thus making the API more programmer
266           friendly. The expression can be any C expression.
267
268       relative
269           The [relative] property can be supplied on a pointer. When it is
270           used it declares the pointer as a spoolss style "relative" pointer,
271           which means it appears on the wire as an offset within the current
272           encapsulating structure. This is not part of normal IDL/NDR, but it
273           is a very useful extension as it avoids the manual encoding of many
274           complex structures.
275
276       subcontext(length)
277           Specifies that a size of length bytes should be read, followed by a
278           blob of that size, which will be parsed as NDR.
279
280           subcontext() is deprecated now, and should not be used in new code.
281           Instead, use represent_as() or transmit_as().
282
283       flag
284           Specify boolean options, mostly used for low-level NDR options.
285           Several options can be specified using the | character.  Note that
286           flags are inherited by substructures!
287
288       nodiscriminant
289           The [nodiscriminant] property on a union means that the usual
290           uint16 discriminent field at the start of the union on the wire is
291           omitted. This is not normally allowed in IDL/NDR, but is used for
292           some spoolss structures.
293
294       charset(name)
295           Specify that the array or string uses the specified charset. If
296           this attribute is specified, pidl will take care of converting the
297           character data from this format to the host format. Commonly used
298           values are UCS2, DOS and UTF8.
299
300   Unsupported MIDL properties or statements
301       aggregatable, appobject, async_uuid, bindable, control, defaultbind,
302       defaultcollelem, defaultvalue, defaultvtable, dispinterface,
303       displaybind, dual, entry, first_is, helpcontext, helpfile,
304       helpstringcontext, helpstringdll, hidden, idl_module, idl_quote, id,
305       immediatebind, importlib, includelib, last_is, lcid, licensed, max_is,
306       module, ms_union, no_injected_text, nonbrowsable, noncreatable,
307       nonextensible, odl, oleautomation, optional, pragma, propget,
308       propputref, propput, readonly, requestedit, restricted, retval, source,
309       uidefault, usesgetlasterror, vararg, vi_progid, wire_marshal.
310

EXAMPLES

312               # Generating an Wireshark parser
313               $ ./pidl --ws-parser -- atsvc.idl
314
315               # Generating a TDR parser and header
316               $ ./pidl --tdr-parser --header -- regf.idl
317
318               # Generating a Samba3 client and server
319               $ ./pidl --samba3-ndr-client --samba3-ndr-server -- dfs.idl
320
321               # Generating a Samba4 NDR parser, client and server
322               $ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl
323

SEE ALSO

325       <https://msdn.microsoft.com/en-us/library/windows/desktop/aa373864%28v=vs.85%29.aspx>
326       <https://wiki.wireshark.org/DCE/RPC>, <https://www.samba.org/>, yapp(1)
327

LICENSE

329       pidl is licensed under the GNU General Public License
330       <https://www.gnu.org/licenses/gpl.html>.
331

AUTHOR

333       pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and
334       Jelmer Vernooij. The current maintainer is Jelmer Vernooij.
335
336       This manpage was written by Jelmer Vernooij, partially based on the
337       original pidl README by Andrew Tridgell.
338
339
340
341perl v5.32.1                      2021-06-01                           PIDL(1)
Impressum