3 ###################################################
4 # package to parse IDL files and generate code for
5 # rpc functions in Samba
6 # Copyright tridge@samba.org 2000-2003
7 # Copyright jelmer@samba.org 2005-2007
8 # released under the GNU GPL
14 pidl - An IDL compiler written in Perl
20 pidl [--outputdir[=OUTNAME]] [--includedir DIR...] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--ndr-parser[=OUTPUT]] [--client] [--server] [--warn-compat] [--quiet] [--verbose] [--template] [--ws-parser[=OUTPUT]] [--diff] [--dump-idl] [--tdr-parser[=OUTPUT]] [--samba3-ndr-client[=OUTPUT]] [--samba3-ndr-server[=OUTPUT]] [<idlfile>.idl]...
24 pidl is an IDL compiler written in Perl that aims to be somewhat
25 compatible with the midl compiler. IDL is short for
26 "Interface Definition Language".
28 pidl can generate stubs for DCE/RPC server code, DCE/RPC
29 client code and Wireshark dissectors for DCE/RPC traffic.
31 IDL compilers like pidl take a description
32 of an interface as their input and use it to generate C
33 (though support for other languages may be added later) code that
34 can use these interfaces, pretty print data sent
35 using these interfaces, or even generate Wireshark
36 dissectors that can parse data sent over the
37 wire by these interfaces.
39 pidl takes IDL files in the same format as is used by midl,
40 converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
41 .pidl files should be used for debugging purposes only. Write your
42 interface definitions in .idl format.
44 The goal of pidl is to implement a IDL compiler that can be used
45 while developing the RPC subsystem in Samba (for
46 both marshalling/unmarshalling and debugging purposes).
54 Show list of available options.
56 =item I<--outputdir OUTNAME>
58 Write output files to the specified directory. Defaults to the current
61 =item I<--includedir DIR>
63 Add DIR to the search path used by the preprocessor. This option can be
64 specified multiple times.
66 =item I<--parse-idl-tree>
68 Read internal tree structure from input files rather
69 than assuming they contain IDL.
73 Generate a new IDL file. File will be named OUTNAME.idl.
77 Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.
81 Generate a C file and C header containing NDR parsers. The filename for
82 the parser defaults to ndr_OUTNAME.c. The header filename will be the
83 parser filename with the extension changed from .c to .h.
87 Generate a C file and C header containing TDR parsers. The filename for
88 the parser defaults to tdr_OUTNAME.c. The header filename will be the
89 parser filename with the extension changed from .c to .h.
93 Generate boilerplate for the RPC server that implements
94 the interface. Filename defaults to ndr_OUTNAME_s.c.
98 Generate stubs for a RPC server that implements the interface. Output will
103 Generate an Wireshark dissector (in C) and header file. The dissector filename
104 defaults to packet-dcerpc-OUTNAME.c while the header filename defaults to
105 packet-dcerpc-OUTNAME.h.
107 Pidl will read additional data from an Wireshark conformance file if present.
108 Such a file should have the same location as the IDL file but with the
109 extension I<cnf> rather than I<idl>. See L<Parse::Pidl::Wireshark::Conformance>
110 for details on the format of this file.
114 Parse an IDL file, generate a new IDL file based on the internal data
115 structures and see if there are any differences with the original IDL file.
116 Useful for debugging pidl.
118 =item I<--dump-idl-tree>
120 Tell pidl to dump the internal tree representation of an IDL
121 file the to disk. Useful for debugging pidl.
123 =item I<--dump-ndr-tree>
125 Tell pidl to dump the internal NDR information tree it generated
126 from the IDL file to disk. Useful for debugging pidl.
128 =item I<--samba3-ndr-client>
130 Generate client calls for Samba3, to be placed in rpc_client/. Instead of
131 calling out to the code in Samba3's rpc_parse/, this will call out to
132 Samba4's NDR code instead.
134 =item I<--samba3-ndr-server>
136 Generate server calls for Samba3, to be placed in rpc_server/. Instead of
137 calling out to the code in Samba3's rpc_parse/, this will call out to
138 Samba4's NDR code instead.
144 IDL files are always preprocessed using the C preprocessor.
146 Pretty much everything in an interface (the interface itself, functions,
147 parameters) can have attributes (or properties whatever name you give them).
148 Attributes always prepend the element they apply to and are surrounded
149 by square brackets ([]). Multiple attributes are separated by comma's;
150 arguments to attributes are specified between parentheses.
152 See the section COMPATIBILITY for the list of attributes that
155 C-style comments can be used.
157 =head2 CONFORMANT ARRAYS
159 A conformant array is one with that ends in [*] or []. The strange
160 things about conformant arrays are that they can only appear as the last
161 element of a structure (unless there is a pointer to the conformant array,
162 of course) and the array size appears before the structure itself on the wire.
170 [size_is(count)] long s[*];
173 it appears like this:
175 [size_is] [abc] [count] [foo] [s...]
177 the first [size_is] field is the allocation size of the array, and
178 occurs before the array elements and even before the structure
181 Note that size_is() can refer to a constant, but that doesn't change
182 the wire representation. It does not make the array a fixed array.
184 midl.exe would write the above array as the following C header:
193 pidl takes a different approach, and writes it like this:
202 =head2 VARYING ARRAYS
204 A varying array looks like this:
210 [size_is(count)] long *s;
213 This will look like this on the wire:
215 [abc] [count] [foo] [PTR_s] [count] [s...]
219 A fixed array looks like this:
225 The NDR representation looks just like 10 separate long
226 declarations. The array size is not encoded on the wire.
228 pidl also supports "inline" arrays, which are not part of the IDL/NDR
229 standard. These are declared like this:
238 This appears like this:
240 [foo] [count] [bar] [s...]
242 Fixed arrays are an extension added to support some of the strange
243 embedded structures in security descriptors and spoolss.
245 This section is by no means complete. See the OpenGroup and MSDN
246 documentation for additional information.
248 =head1 COMPATIBILITY WITH MIDL
250 =head2 Missing features in pidl
252 The following MIDL features are not (yet) implemented in pidl
253 or are implemented with an incompatible interface:
259 Asynchronous communication
263 Typelibs (.tlb files)
267 Datagram support (ncadg_*)
271 =head2 Supported attributes and statements
273 in, out, ref, length_is, switch_is, size_is, uuid, case, default, string,
274 unique, ptr, pointer_default, v1_enum, object, helpstring, range, local,
275 call_as, endpoint, switch_type, progid, coclass, iid_is, represent_as,
276 transmit_as, import, include.
278 =head2 PIDL Specific properties
284 The [public] property on a structure or union is a pidl extension that
285 forces the generated pull/push functions to be non-static. This allows
286 you to declare types that can be used between modules. If you don't
287 specify [public] then pull/push functions for other than top-level
288 functions are declared static.
292 The [noprint] property is a pidl extension that allows you to specify
293 that pidl should not generate a ndr_print_*() function for that
294 structure or union. This is used when you wish to define your own
295 print function that prints a structure in a nicer manner. A good
296 example is the use of [noprint] on dom_sid, which allows the
297 pretty-printing of SIDs.
301 The [value(expression)] property is a pidl extension that allows you
302 to specify the value of a field when it is put on the wire. This
303 allows fields that always have a well-known value to be automatically
304 filled in, thus making the API more programmer friendly. The
305 expression can be any C expression.
309 The [relative] property can be supplied on a pointer. When it is used
310 it declares the pointer as a spoolss style "relative" pointer, which
311 means it appears on the wire as an offset within the current
312 encapsulating structure. This is not part of normal IDL/NDR, but it is
313 a very useful extension as it avoids the manual encoding of many
316 =item subcontext(length)
318 Specifies that a size of I<length>
319 bytes should be read, followed by a blob of that size,
320 which will be parsed as NDR.
322 subcontext() is deprecated now, and should not be used in new code.
323 Instead, use represent_as() or transmit_as().
327 Specify boolean options, mostly used for
328 low-level NDR options. Several options
329 can be specified using the | character.
330 Note that flags are inherited by substructures!
334 The [nodiscriminant] property on a union means that the usual uint16
335 discriminent field at the start of the union on the wire is
336 omitted. This is not normally allowed in IDL/NDR, but is used for some
341 Specify that the array or string uses the specified
342 charset. If this attribute is specified, pidl will
343 take care of converting the character data from this format
344 to the host format. Commonly used values are UCS2, DOS and UTF8.
348 =head2 Unsupported MIDL properties or statements
350 aggregatable, appobject, async_uuid, bindable, control, cpp_quote,
351 defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface,
352 displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext,
353 helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib,
354 includelib, last_is, lcid, licensed, max_is, module,
355 ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl,
356 oleautomation, optional, pragma, propget, propputref, propput, readonly,
357 requestedit, restricted, retval, source, uidefault,
358 usesgetlasterror, vararg, vi_progid, wire_marshal.
362 # Generating an Wireshark parser
363 $ ./pidl --ws-parser -- atsvc.idl
365 # Generating a TDR parser and header
366 $ ./pidl --tdr-parser --header -- regf.idl
368 # Generating a Samba3 client and server
369 $ ./pidl --samba3-ndr-client --samba3-ndr-server -- dfs.idl
371 # Generating a Samba4 NDR parser, client and server
372 $ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl
376 L<http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp>,
377 L<http://wiki.wireshark.org/DCE/RPC>,
378 L<http://www.samba.org/>,
383 pidl is licensed under the GNU General Public License L<http://www.gnu.org/licenses/gpl.html>.
387 pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer
388 Vernooij. The current maintainer is Jelmer Vernooij.
390 This manpage was written by Jelmer Vernooij, partially based on the original
391 pidl README by Andrew Tridgell.
397 use FindBin qw($RealBin $Script);
399 use lib "$RealBin/lib";
403 use Parse::Pidl::Util;
405 #####################################################################
406 # save a data structure into a file
407 sub SaveStructure($$)
409 my($filename,$v) = @_;
410 FileSave($filename, Parse::Pidl::Util::MyDumper($v));
413 #####################################################################
414 # load a data structure from a file (as saved with SaveStructure)
418 my $contents = FileLoad($f);
419 defined $contents || return undef;
420 return eval "$contents";
423 #####################################################################
424 # read a file into a string
427 my($filename) = shift;
429 open(INPUTFILE, $filename) || return undef;
430 my($saved_delim) = $/;
432 my($data) = <INPUTFILE>;
438 #####################################################################
439 # write a string into a file
442 my($filename) = shift;
445 open(FILE, ">$filename") || die "can't open $filename";
450 my(@opt_incdirs) = ();
452 my($opt_parse_idl_tree) = 0;
453 my($opt_dump_idl_tree);
454 my($opt_dump_ndr_tree);
455 my($opt_dump_idl) = 0;
458 my($opt_samba3_header);
459 my($opt_samba3_parser);
460 my($opt_samba3_server);
461 my($opt_samba3_ndr_client);
462 my($opt_samba3_ndr_server);
463 my($opt_template) = 0;
472 my($opt_outputdir) = '.';
473 my($opt_verbose) = 0;
474 my($opt_warn_compat) = 0;
476 #########################################
480 print "perl IDL parser and code generator
481 Copyright (C) Andrew Tridgell <tridge\@samba.org>
482 Copyright (C) Jelmer Vernooij <jelmer\@samba.org>
484 Usage: $Script [options] [--] <idlfile> [<idlfile>...]
487 --help this help page
488 --outputdir=OUTDIR put output in OUTDIR/ [.]
489 --warn-compat warn about incompatibility with other compilers
492 --includedir DIR search DIR for included files
495 --dump-idl-tree[=FILE] dump internal representation to file [BASENAME.pidl]
496 --parse-idl-tree read internal representation instead of IDL
497 --dump-ndr-tree[=FILE] dump internal NDR data tree to file [BASENAME.ndr]
498 --dump-idl regenerate IDL file
499 --diff run diff on original IDL and dumped output
502 --header[=OUTFILE] create generic header file [BASENAME.h]
503 --ndr-parser[=OUTFILE] create a C NDR parser [ndr_BASENAME.c]
504 --client[=OUTFILE] create a C NDR client [ndr_BASENAME_c.c]
505 --tdr-parser[=OUTFILE] create a C TDR parser [tdr_BASENAME.c]
506 --ejs[=OUTFILE] create ejs wrapper file [BASENAME_ejs.c]
507 --swig[=OUTFILE] create swig wrapper file [BASENAME.i]
508 --server[=OUTFILE] create server boilerplate [ndr_BASENAME_s.c]
509 --template print a template for a pipe
512 --samba3-ndr-client[=OUTF] create client calls for Samba3
513 using Samba4's NDR code [cli_BASENAME.c]
514 --samba3-ndr-server[=OUTF] create server call wrapper for Samba3
515 using Samba4's NDR code [srv_BASENAME.c]
518 --ws-parser[=OUTFILE] create Wireshark parser and header
524 my $result = GetOptions (
525 'help|h|?' => \$opt_help,
526 'outputdir=s' => \$opt_outputdir,
527 'dump-idl' => \$opt_dump_idl,
528 'dump-idl-tree:s' => \$opt_dump_idl_tree,
529 'parse-idl-tree' => \$opt_parse_idl_tree,
530 'dump-ndr-tree:s' => \$opt_dump_ndr_tree,
531 'samba3-ndr-client:s' => \$opt_samba3_ndr_client,
532 'samba3-ndr-server:s' => \$opt_samba3_ndr_server,
533 'header:s' => \$opt_header,
534 'server:s' => \$opt_server,
535 'tdr-parser:s' => \$opt_tdr_parser,
536 'template' => \$opt_template,
537 'ndr-parser:s' => \$opt_ndr_parser,
538 'client:s' => \$opt_client,
539 'ws-parser:s' => \$opt_ws_parser,
541 'diff' => \$opt_diff,
542 'swig:s' => \$opt_swig,
543 'quiet' => \$opt_quiet,
544 'verbose' => \$opt_verbose,
545 'warn-compat' => \$opt_warn_compat,
546 'includedir=s@' => \@opt_incdirs
560 my $idl_file = shift;
561 my $outputdir = $opt_outputdir;
565 my $basename = basename($idl_file, ".idl");
567 unless ($opt_quiet) { print "Compiling $idl_file\n"; }
569 if ($opt_parse_idl_tree) {
570 $pidl = LoadStructure($idl_file);
571 defined $pidl || die "Failed to load $idl_file";
573 require Parse::Pidl::IDL;
575 $pidl = Parse::Pidl::IDL::parse_file($idl_file, \@opt_incdirs);
576 defined @$pidl || die "Failed to parse $idl_file";
577 require Parse::Pidl::Typelist;
578 Parse::Pidl::Typelist::LoadIdl($pidl);
581 if (defined($opt_dump_idl_tree)) {
582 my($pidl_file) = ($opt_dump_idl_tree or "$outputdir/$basename.pidl");
583 SaveStructure($pidl_file, $pidl) or die "Failed to save $pidl_file\n";
587 require Parse::Pidl::Dump;
588 print Parse::Pidl::Dump($pidl);
592 my($tempfile) = "$outputdir/$basename.tmp";
593 FileSave($tempfile, IdlDump::Dump($pidl));
594 system("diff -wu $idl_file $tempfile");
598 if ($opt_warn_compat) {
599 require Parse::Pidl::Compat;
600 Parse::Pidl::Compat::Check($pidl);
603 if (defined($opt_ws_parser) or
604 defined($opt_client) or defined($opt_server) or
605 defined($opt_ndr_parser) or defined($opt_ejs) or
606 defined($opt_dump_ndr_tree) or defined($opt_samba3_header) or
607 defined($opt_samba3_parser) or defined($opt_samba3_server) or
608 defined($opt_swig) or defined($opt_samba3_ndr_client) or
609 defined($opt_samba3_ndr_server)) {
610 require Parse::Pidl::NDR;
611 $ndr = Parse::Pidl::NDR::Parse($pidl);
614 if (defined($opt_dump_ndr_tree)) {
615 my($ndr_file) = ($opt_dump_ndr_tree or "$outputdir/$basename.ndr");
616 SaveStructure($ndr_file, $ndr) or die "Failed to save $ndr_file\n";
619 my $gen_header = ($opt_header or "$outputdir/$basename.h");
620 if (defined($opt_header)) {
621 require Parse::Pidl::Samba4::Header;
622 FileSave($gen_header, Parse::Pidl::Samba4::Header::Parse($pidl));
625 my $h_filename = "$outputdir/ndr_$basename.h";
626 if (defined($opt_client)) {
627 require Parse::Pidl::Samba4::NDR::Client;
628 my ($c_client) = ($opt_client or "$outputdir/ndr_$basename\_c.c");
629 my ($c_header) = $c_client;
630 $c_header =~ s/\.c$/.h/;
632 my ($srcd,$hdrd) = Parse::Pidl::Samba4::NDR::Client::Parse(
633 $ndr,$gen_header,$h_filename,$c_header);
635 FileSave($c_client, $srcd);
636 FileSave($c_header, $hdrd);
639 if (defined($opt_swig)) {
640 require Parse::Pidl::Samba4::SWIG;
641 my($filename) = ($opt_swig or "$outputdir/$basename.i");
642 my $code = Parse::Pidl::Samba4::SWIG::Parse($ndr, $basename, "$outputdir/ndr_$basename\_c.h", $gen_header);
643 FileSave($filename, $code);
646 if (defined($opt_ejs)) {
647 require Parse::Pidl::Samba4::EJS;
648 my $generator = new Parse::Pidl::Samba4::EJS();
649 my ($hdr,$prsr) = $generator->Parse($ndr, $h_filename);
650 FileSave("$outputdir/ndr_$basename\_ejs.c", $prsr);
651 FileSave("$outputdir/ndr_$basename\_ejs.h", $hdr);
654 if (defined($opt_server)) {
655 require Parse::Pidl::Samba4::NDR::Server;
657 FileSave(($opt_server or "$outputdir/ndr_$basename\_s.c"), Parse::Pidl::Samba4::NDR::Server::Parse($ndr,$h_filename));
660 if (defined($opt_ndr_parser)) {
661 my $parser_fname = ($opt_ndr_parser or "$outputdir/ndr_$basename.c");
662 require Parse::Pidl::Samba4::NDR::Parser;
663 my ($header,$parser) = Parse::Pidl::Samba4::NDR::Parser::Parse($ndr, $gen_header, $h_filename);
666 FileSave($parser_fname, $parser);
667 FileSave($h_filename, $header);
671 if (defined($opt_ws_parser)) {
672 require Parse::Pidl::Wireshark::NDR;
673 my($eparser) = ($opt_ws_parser or "$outputdir/packet-dcerpc-$basename.c");
674 my $eheader = $eparser;
675 $eheader =~ s/\.c$/\.h/;
676 my $cnffile = $idl_file;
677 $cnffile =~ s/\.idl$/\.cnf/;
679 my $generator = new Parse::Pidl::Wireshark::NDR();
680 my ($dp, $dh) = $generator->Parse($ndr, $idl_file, $eheader, $cnffile);
681 FileSave($eparser, $dp) if defined($dp);
682 FileSave($eheader, $dh) if defined($dh);
685 if (defined($opt_tdr_parser)) {
686 my $tdr_parser = ($opt_tdr_parser or "$outputdir/tdr_$basename.c");
687 my $tdr_header = $tdr_parser;
688 $tdr_header =~ s/\.c$/\.h/;
689 require Parse::Pidl::Samba4::TDR;
690 my $generator = new Parse::Pidl::Samba4::TDR();
691 my ($hdr,$prsr) = $generator->Parser($pidl, $tdr_header, $gen_header);
692 FileSave($tdr_parser, $prsr);
693 FileSave($tdr_header, $hdr);
697 require Parse::Pidl::Samba4::Template;
698 print Parse::Pidl::Samba4::Template::Parse($pidl);
701 if (defined($opt_samba3_ndr_client)) {
702 my $client = ($opt_samba3_ndr_client or "$outputdir/cli_$basename.c");
703 my $header = $client; $header =~ s/\.c$/\.h/;
704 require Parse::Pidl::Samba3::ClientNDR;
705 my ($c_code,$h_code) = Parse::Pidl::Samba3::ClientNDR::Parse($ndr, $header, $h_filename);
706 FileSave($client, $c_code);
707 FileSave($header, $h_code);
710 if (defined($opt_samba3_ndr_server)) {
711 my $server = ($opt_samba3_ndr_server or "$outputdir/srv_$basename.c");
712 my $header = $server; $header =~ s/\.c$/\.h/;
713 require Parse::Pidl::Samba3::ServerNDR;
714 my ($c_code,$h_code) = Parse::Pidl::Samba3::ServerNDR::Parse($ndr, $header, $h_filename);
715 FileSave($server, $c_code);
716 FileSave($header, $h_code);
721 if (scalar(@ARGV) == 0) {
722 print "$Script: no input files\n";
726 process_file($_) foreach (@ARGV);