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]] [--python[=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, cpp_quote.
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,
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;
473 my($opt_outputdir) = '.';
474 my($opt_verbose) = 0;
475 my($opt_warn_compat) = 0;
477 #########################################
481 print "perl IDL parser and code generator
482 Copyright (C) Andrew Tridgell <tridge\@samba.org>
483 Copyright (C) Jelmer Vernooij <jelmer\@samba.org>
485 Usage: $Script [options] [--] <idlfile> [<idlfile>...]
488 --help this help page
489 --outputdir=OUTDIR put output in OUTDIR/ [.]
490 --warn-compat warn about incompatibility with other compilers
493 --includedir DIR search DIR for included files
496 --dump-idl-tree[=FILE] dump internal representation to file [BASENAME.pidl]
497 --parse-idl-tree read internal representation instead of IDL
498 --dump-ndr-tree[=FILE] dump internal NDR data tree to file [BASENAME.ndr]
499 --dump-idl regenerate IDL file
500 --diff run diff on original IDL and dumped output
503 --header[=OUTFILE] create generic header file [BASENAME.h]
504 --ndr-parser[=OUTFILE] create a C NDR parser [ndr_BASENAME.c]
505 --client[=OUTFILE] create a C NDR client [ndr_BASENAME_c.c]
506 --tdr-parser[=OUTFILE] create a C TDR parser [tdr_BASENAME.c]
507 --ejs[=OUTFILE] create ejs wrapper file [BASENAME_ejs.c]
508 --python[=OUTFILE] create python wrapper file [py_BASENAME.c]
509 --swig[=OUTFILE] create swig wrapper file [BASENAME.i]
510 --server[=OUTFILE] create server boilerplate [ndr_BASENAME_s.c]
511 --template print a template for a pipe
514 --samba3-ndr-client[=OUTF] create client calls for Samba3
515 using Samba4's NDR code [cli_BASENAME.c]
516 --samba3-ndr-server[=OUTF] create server call wrapper for Samba3
517 using Samba4's NDR code [srv_BASENAME.c]
520 --ws-parser[=OUTFILE] create Wireshark parser and header
526 my $result = GetOptions (
527 'help|h|?' => \$opt_help,
528 'outputdir=s' => \$opt_outputdir,
529 'dump-idl' => \$opt_dump_idl,
530 'dump-idl-tree:s' => \$opt_dump_idl_tree,
531 'parse-idl-tree' => \$opt_parse_idl_tree,
532 'dump-ndr-tree:s' => \$opt_dump_ndr_tree,
533 'samba3-ndr-client:s' => \$opt_samba3_ndr_client,
534 'samba3-ndr-server:s' => \$opt_samba3_ndr_server,
535 'header:s' => \$opt_header,
536 'server:s' => \$opt_server,
537 'tdr-parser:s' => \$opt_tdr_parser,
538 'template' => \$opt_template,
539 'ndr-parser:s' => \$opt_ndr_parser,
540 'client:s' => \$opt_client,
541 'ws-parser:s' => \$opt_ws_parser,
543 'python' => \$opt_python,
544 'diff' => \$opt_diff,
545 'swig:s' => \$opt_swig,
546 'quiet' => \$opt_quiet,
547 'verbose' => \$opt_verbose,
548 'warn-compat' => \$opt_warn_compat,
549 'includedir=s@' => \@opt_incdirs
563 my $idl_file = shift;
564 my $outputdir = $opt_outputdir;
568 my $basename = basename($idl_file, ".idl");
570 unless ($opt_quiet) { print "Compiling $idl_file\n"; }
572 if ($opt_parse_idl_tree) {
573 $pidl = LoadStructure($idl_file);
574 defined $pidl || die "Failed to load $idl_file";
576 require Parse::Pidl::IDL;
578 $pidl = Parse::Pidl::IDL::parse_file($idl_file, \@opt_incdirs);
579 defined @$pidl || die "Failed to parse $idl_file";
580 require Parse::Pidl::Typelist;
581 Parse::Pidl::Typelist::LoadIdl($pidl);
584 if (defined($opt_dump_idl_tree)) {
585 my($pidl_file) = ($opt_dump_idl_tree or "$outputdir/$basename.pidl");
586 SaveStructure($pidl_file, $pidl) or die "Failed to save $pidl_file\n";
590 require Parse::Pidl::Dump;
591 print Parse::Pidl::Dump($pidl);
595 my($tempfile) = "$outputdir/$basename.tmp";
596 FileSave($tempfile, IdlDump::Dump($pidl));
597 system("diff -wu $idl_file $tempfile");
601 if ($opt_warn_compat) {
602 require Parse::Pidl::Compat;
603 Parse::Pidl::Compat::Check($pidl);
606 if (defined($opt_ws_parser) or
607 defined($opt_client) or
608 defined($opt_server) or
609 defined($opt_header) or
610 defined($opt_ndr_parser) or
612 defined($opt_python) or
613 defined($opt_dump_ndr_tree) or
614 defined($opt_samba3_header) or
615 defined($opt_samba3_parser) or
616 defined($opt_samba3_server) or
617 defined($opt_swig) or
618 defined($opt_samba3_ndr_client) or
619 defined($opt_samba3_ndr_server)) {
620 require Parse::Pidl::NDR;
621 $ndr = Parse::Pidl::NDR::Parse($pidl);
624 if (defined($opt_dump_ndr_tree)) {
625 my($ndr_file) = ($opt_dump_ndr_tree or "$outputdir/$basename.ndr");
626 SaveStructure($ndr_file, $ndr) or die "Failed to save $ndr_file\n";
629 my $gen_header = ($opt_header or "$outputdir/$basename.h");
630 if (defined($opt_header)) {
631 require Parse::Pidl::Samba4::Header;
632 FileSave($gen_header, Parse::Pidl::Samba4::Header::Parse($ndr));
635 my $h_filename = "$outputdir/ndr_$basename.h";
636 if (defined($opt_client)) {
637 require Parse::Pidl::Samba4::NDR::Client;
638 my ($c_client) = ($opt_client or "$outputdir/ndr_$basename\_c.c");
639 my ($c_header) = $c_client;
640 $c_header =~ s/\.c$/.h/;
642 my ($srcd,$hdrd) = Parse::Pidl::Samba4::NDR::Client::Parse(
643 $ndr,$gen_header,$h_filename,$c_header);
645 FileSave($c_client, $srcd);
646 FileSave($c_header, $hdrd);
649 if (defined($opt_swig)) {
650 require Parse::Pidl::Samba4::SWIG;
651 my($filename) = ($opt_swig or "$outputdir/$basename.i");
652 my $code = Parse::Pidl::Samba4::SWIG::Parse($ndr, $basename, "$outputdir/ndr_$basename\_c.h", $gen_header);
653 FileSave($filename, $code);
656 if (defined($opt_ejs)) {
657 require Parse::Pidl::Samba4::EJS;
658 my $generator = new Parse::Pidl::Samba4::EJS();
659 my ($hdr,$prsr) = $generator->Parse($ndr, $h_filename);
660 FileSave("$outputdir/ndr_$basename\_ejs.c", $prsr);
661 FileSave("$outputdir/ndr_$basename\_ejs.h", $hdr);
664 if (defined($opt_python)) {
665 require Parse::Pidl::Samba4::Python;
666 my $generator = new Parse::Pidl::Samba4::Python();
667 my ($hdr,$prsr) = $generator->Parse($basename, $ndr, $h_filename);
668 FileSave("$outputdir/py_$basename.c", $prsr);
669 FileSave("$outputdir/py_$basename.h", $hdr);
672 if (defined($opt_server)) {
673 require Parse::Pidl::Samba4::NDR::Server;
675 FileSave(($opt_server or "$outputdir/ndr_$basename\_s.c"), Parse::Pidl::Samba4::NDR::Server::Parse($ndr,$h_filename));
678 if (defined($opt_ndr_parser)) {
679 my $parser_fname = ($opt_ndr_parser or "$outputdir/ndr_$basename.c");
680 require Parse::Pidl::Samba4::NDR::Parser;
681 my $generator = new Parse::Pidl::Samba4::NDR::Parser();
682 my ($header,$parser) = $generator->Parse($ndr, $gen_header, $h_filename);
684 FileSave($parser_fname, $parser);
685 FileSave($h_filename, $header);
689 if (defined($opt_ws_parser)) {
690 require Parse::Pidl::Wireshark::NDR;
691 my($eparser) = ($opt_ws_parser or "$outputdir/packet-dcerpc-$basename.c");
692 my $eheader = $eparser;
693 $eheader =~ s/\.c$/\.h/;
694 my $cnffile = $idl_file;
695 $cnffile =~ s/\.idl$/\.cnf/;
697 my $generator = new Parse::Pidl::Wireshark::NDR();
698 my ($dp, $dh) = $generator->Parse($ndr, $idl_file, $eheader, $cnffile);
699 FileSave($eparser, $dp) if defined($dp);
700 FileSave($eheader, $dh) if defined($dh);
703 if (defined($opt_tdr_parser)) {
704 my $tdr_parser = ($opt_tdr_parser or "$outputdir/tdr_$basename.c");
705 my $tdr_header = $tdr_parser;
706 $tdr_header =~ s/\.c$/\.h/;
707 require Parse::Pidl::Samba4::TDR;
708 my $generator = new Parse::Pidl::Samba4::TDR();
709 my ($hdr,$prsr) = $generator->Parser($pidl, $tdr_header, $gen_header);
710 FileSave($tdr_parser, $prsr);
711 FileSave($tdr_header, $hdr);
715 require Parse::Pidl::Samba4::Template;
716 print Parse::Pidl::Samba4::Template::Parse($pidl);
719 if (defined($opt_samba3_ndr_client)) {
720 my $client = ($opt_samba3_ndr_client or "$outputdir/cli_$basename.c");
721 my $header = $client; $header =~ s/\.c$/\.h/;
722 require Parse::Pidl::Samba3::ClientNDR;
723 my $generator = new Parse::Pidl::Samba3::ClientNDR();
724 my ($c_code,$h_code) = $generator->Parse($ndr, $header, $h_filename);
725 FileSave($client, $c_code);
726 FileSave($header, $h_code);
729 if (defined($opt_samba3_ndr_server)) {
730 my $server = ($opt_samba3_ndr_server or "$outputdir/srv_$basename.c");
731 my $header = $server; $header =~ s/\.c$/\.h/;
732 require Parse::Pidl::Samba3::ServerNDR;
733 my ($c_code,$h_code) = Parse::Pidl::Samba3::ServerNDR::Parse($ndr, $header, $h_filename);
734 FileSave($server, $c_code);
735 FileSave($header, $h_code);
740 if (scalar(@ARGV) == 0) {
741 print "$Script: no input files\n";
745 process_file($_) foreach (@ARGV);