1PIDL(1) Samba Documentation PIDL(1)
2
6 pidl - An IDL compiler written in Perl
7
9 pidl --help
10 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
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 pidl can generate stubs for DCE/RPC server code, DCE/RPC client code
25 and Wireshark dissectors for DCE/RPC traffic.
26 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 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 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
44 --help
45 Show list of available options.
46 --version
48 Show pidl version
49 --outputdir OUTNAME
51 Write output files to the specified directory. Defaults to the
52 current directory.
53 --includedir DIR
55 Add DIR to the search path used by the preprocessor. This option
56 can be specified multiple times.
57 --parse-idl-tree
59 Read internal tree structure from input files rather than assuming
60 they contain IDL.
61 --dump-idl
63 Generate a new IDL file. File will be named OUTNAME.idl.
64 --header
66 Generate a C header file for the specified interface. Filename
67 defaults to OUTNAME.h.
68 --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 --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 --typelib
80 Write type information to the specified file.
81 --server
83 Generate boilerplate for the RPC server that implements the
84 interface. Filename defaults to ndr_OUTNAME_s.c.
85 --template
87 Generate stubs for a RPC server that implements the interface.
88 Output will be written to stdout.
89 --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 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 --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 --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 --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 --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 --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
125 IDL files are always preprocessed using the C preprocessor.
126 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 See the section COMPATIBILITY for the list of attributes that pidl
135 supports.
136 C-style comments can be used.
138 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 So, in this example:
147 typedef struct {
149 long abc;
150 long count;
151 long foo;
152 [size_is(count)] long s[*];
153 } Struct1;
154 it appears like this:
156 [size_is] [abc] [count] [foo] [s...]
158 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 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 midl.exe would write the above array as the following C header:
167 typedef struct {
169 long abc;
170 long count;
171 long foo;
172 long s[1];
173 } Struct1;
174 pidl takes a different approach, and writes it like this:
176 typedef struct {
178 long abc;
179 long count;
180 long foo;
181 long *s;
182 } Struct1;
183 VARYING ARRAYS
185 A varying array looks like this:
186 typedef struct {
188 long abc;
189 long count;
190 long foo;
191 [size_is(count)] long *s;
192 } Struct1;
193 This will look like this on the wire:
195 [abc] [count] [foo] [PTR_s] [count] [s...]
197 FIXED ARRAYS
199 A fixed array looks like this:
200 typedef struct {
202 long s[10];
203 } Struct1;
204 The NDR representation looks just like 10 separate long declarations.
206 The array size is not encoded on the wire.
207 pidl also supports "inline" arrays, which are not part of the IDL/NDR
209 standard. These are declared like this:
210 typedef struct {
212 uint32 foo;
213 uint32 count;
214 uint32 bar;
215 long s[count];
216 } Struct1;
217 This appears like this:
219 [foo] [count] [bar] [s...]
221 Fixed arrays are an extension added to support some of the strange
223 embedded structures in security descriptors and spoolss.
224 This section is by no means complete. See the OpenGroup and MSDN
226 documentation for additional information.
227
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 · Asynchronous communication
234 · Typelibs (.tlb files)
236 · Datagram support (ncadg_*)
238 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 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 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 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 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 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 subcontext() is deprecated now, and should not be used in new code.
281 Instead, use represent_as() or transmit_as().
282 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 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 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 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
312 # Generating an Wireshark parser
313 $ ./pidl --ws-parser -- atsvc.idl
314 # Generating a TDR parser and header
316 $ ./pidl --tdr-parser --header -- regf.idl
317 # Generating a Samba3 client and server
319 $ ./pidl --samba3-ndr-client --samba3-ndr-server -- dfs.idl
320 # Generating a Samba4 NDR parser, client and server
322 $ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl
323
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
329 pidl is licensed under the GNU General Public License
330 <https://www.gnu.org/licenses/gpl.html>.
331
333 pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and
334 Jelmer Vernooij. The current maintainer is Jelmer Vernooij.
335 This manpage was written by Jelmer Vernooij, partially based on the
337 original pidl README by Andrew Tridgell.
338perl v5.28.2 2018-07-12 PIDL(1)