r10190: Do some very basic input checking when provisioning.
[jra/samba/.git] / source4 / pidl / pidl.1.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="pidl.1">
4
5 <refmeta>
6         <refentrytitle>pidl</refentrytitle>
7         <manvolnum>1</manvolnum>
8 </refmeta>
9
10 <refnamediv>
11         <refname>pidl</refname>
12         <refpurpose>IDL Compiler written in Perl</refpurpose>
13 </refnamediv>
14
15 <refsynopsisdiv>
16         <cmdsynopsis>
17                 <command>pidl</command>
18                 <arg choice="opt">--help</arg>
19                 <arg choice="opt">--outputdir OUTNAME</arg>
20                 <arg choice="opt">--parse-idl-tree</arg>
21                 <arg choice="opt">--dump-idl-tree</arg>
22                 <arg choice="opt">--dump-ndr-tree</arg>
23                 <arg choice="opt">--ndr-header[=OUTPUT]</arg>
24                 <arg choice="opt">--header[=OUTPUT]</arg>
25                 <arg choice="opt">--ejs[=OUTPUT]</arg>
26                 <arg choice="opt">--swig[=OUTPUT]</arg>
27                 <arg choice="opt">--uint-enums</arg>
28                 <arg choice="opt">--ndr-parser[=OUTPUT]</arg>
29                 <arg choice="opt">--client</arg>
30                 <arg choice="opt">--server</arg>
31                 <arg choice="opt">--dcom-proxy</arg>
32                 <arg choice="opt">--com-header</arg>
33                 <arg choice="opt">--warn-compat</arg>
34                 <arg choice="opt">--quiet</arg>
35                 <arg choice="opt">--verbose</arg>
36                 <arg choice="opt">--template</arg>
37                 <arg choice="opt">--eth-parser[=OUTPUT]</arg>
38                 <arg choice="opt">--diff</arg>
39                 <arg choice="opt">--dump-idl</arg>
40                 <arg choice="req">idlfile</arg>
41                 <arg choice="opt">idlfile2</arg>
42                 <arg choice="opt">...</arg>
43         </cmdsynopsis>
44 </refsynopsisdiv>
45
46 <refsect1>
47         <title>DESCRIPTION</title>
48
49         <para>pidl is an IDL compiler written in Perl that aims to be somewhat 
50                 compatible with the midl compiler. IDL stands for 
51                 "Interface Definition Language".</para>
52
53         <para>pidl can generate stubs for DCE/RPC server code, DCE/RPC 
54                 client code and ethereal dissectors for DCE/RPC traffic.</para>
55
56         <para>IDL compilers like <emphasis>pidl</emphasis> take a description 
57                 of an interface as their input and use it to generate C 
58                 (though support for other languages may be added later) code that 
59                 can use these interfaces, pretty print data sent 
60                 using these interfaces, or even generate ethereal 
61                 dissectors that can parse data sent over the 
62                 wire by these interfaces. </para>
63
64         <para>pidl takes IDL files in the same format as is used by midl, 
65                 converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
66                 .pidl files should be used for debugging purposes only. Write your 
67                 interface definitions in .idl format.
68         </para>
69
70         <para>
71                 The goal of pidl is to implement a IDL compiler that can be used 
72                 while developing the RPC subsystem in Samba (for 
73                 both marshalling/unmarshalling and debugging purposes).
74         </para>
75
76 </refsect1>
77
78 <refsect1>
79         <title>OPTIONS</title>
80
81         <variablelist>
82                 <varlistentry>
83                 <term>--help</term>
84                 <listitem><para>
85                 Show list of available options.</para></listitem>
86                 </varlistentry>
87                 
88                 <varlistentry>
89                 <term>--outputdir OUTNAME</term>
90                 <listitem><para>Write output files to the specified directory. 
91                                 Defaults to the current directory.
92                 </para></listitem>
93                 </varlistentry>
94                 
95                 <varlistentry>
96                 <term>--parse-idl-tree</term>
97                 <listitem><para>
98                                 Read internal tree structure from input files rather 
99                 then assuming they contain IDL.</para></listitem>
100                 </varlistentry>
101
102
103                 <varlistentry>
104                 <term>--dump-idl</term>
105                 <listitem><para>
106                                 Generate a new IDL file. File will be named OUTNAME.idl.</para></listitem>
107                 </varlistentry>
108
109
110                 <varlistentry>
111                 <term>--header</term>
112                 <listitem><para>
113                                 Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.</para></listitem>
114                 </varlistentry>
115
116                 <varlistentry>
117                 <term>--ndr-header</term>
118                 <listitem><para>
119                                 Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.</para></listitem>
120                 </varlistentry>
121
122                 <varlistentry>
123                 <term>--ndr-parser</term>
124                 <listitem><para>
125                                 Generate a C file containing NDR parsers. 
126                                 Filename defaults to ndr_OUTNAME.c.
127                 </para></listitem>
128                 </varlistentry>
129
130
131                 <varlistentry>
132                 <term>--server</term>
133                 <listitem><para>
134                 Generate boilerplate for the RPC server that implements 
135                 the interface. Filename defaults to ndr_OUTNAME_s.c</para></listitem>
136                 </varlistentry>
137
138
139                 <varlistentry>
140                 <term>--template</term>
141                 <listitem><para>
142                 Generate stubs for a RPC server that implements 
143                 the interface. Output will be written to stdout.
144                 </para></listitem>
145                 </varlistentry>
146
147
148                 <varlistentry>
149                 <term>--eth-parser</term>
150                 <listitem><para>
151                 Generate an Ethereal dissector (in C) for the interface. Filename
152                 defaults to packet-dcerpc-OUTNAME.c. 
153                 </para>
154         
155                 <para>Pidl will read additional data 
156                         from an ethereal conformance file if present. Such a file should 
157                         have the same location as the IDL file but with the extension 
158                         <quote>cnf</quote> rather then <quote>idl</quote>. See 
159                         below for details on the format of this file.
160                 </para></listitem>
161                 </varlistentry>
162
163                 <varlistentry>
164                 <term>--diff</term>
165                 <listitem><para>
166                                 Parse an IDL file,  generate a new IDL file based 
167                                 on the internal data structures and see if there are 
168                                 any differences with the 
169                 original IDL file. Useful for debugging pidl.</para></listitem>
170                 </varlistentry>
171
172
173                 <varlistentry>
174                 <term>--dump-idl-tree</term>
175                 <listitem><para>
176                 Tell pidl to dump the internal tree representation of an IDL 
177                 file the to disk. Useful 
178                 for debugging pidl.</para></listitem>
179                 </varlistentry>
180
181                 <varlistentry>
182                 <term>--dump-ndr-tree</term>
183                 <listitem><para>
184                                 Tell pidl to dump the internal NDR information tree it generated 
185                                 from the IDL file to disk.  Useful for debugging pidl.</para></listitem>
186                 </varlistentry>
187
188         </variablelist>
189 </refsect1>
190
191 <refsect1>
192         <title>IDL SYNTAX</title>
193
194         <para>IDL files are always preprocessed using the C preprocessor.</para>
195
196         <para>Pretty much everything in an interface (the interface itself,
197                 functions, parameters) can have attributes (or properties 
198                 whatever name you give them). Attributes 
199                 always prepend the element they apply to and are surrounded 
200                 by square brackets ([]). Multiple attributes 
201                 are separated by comma's; arguments to attributes are 
202                 specified between parentheses. </para>
203
204         <para>See the section COMPATIBILITY for the list of attributes that 
205                 pidl supports.</para>
206
207         <para>C-style comments can be used.</para>
208         
209 <refsect2>
210         <title>CONFORMANT ARRAYS</title>
211
212         <para>
213 A conformant array is one with that ends in [*] or []. The strange
214 things about conformant arrays are:
215 </para>
216
217 <simplelist>
218         <member>they can only appear as the last element of a structure</member>
219         <member>the array size appears before the structure itself on the wire. </member>
220 </simplelist>
221
222 <para>
223         So, in this example:
224 </para>
225
226 <programlisting>
227         typedef struct {
228                 long abc;
229                 long count;     
230                 long foo;
231                 [size_is(count)] long s[*];
232         } Struct1;
233 </programlisting>
234
235 <para>
236 it appears like this:
237 </para>
238
239 <programlisting>
240 [size_is] [abc] [count] [foo] [s...]
241 </programlisting>
242
243 <para>
244 the first [size_is] field is the allocation size of the array, and
245 occurs before the array elements and even before the structure
246 alignment.
247 </para>
248
249 <para>
250 Note that size_is() can refer to a constant, but that doesn't change
251 the wire representation. It does not make the array a fixed array.
252 </para>
253
254 <para>
255 midl.exe would write the above array as the following C header:
256 </para>
257
258 <programlisting>
259    typedef struct {
260                 long abc;
261                 long count;     
262                 long foo;
263                 long s[1];
264         } Struct1;
265 </programlisting>
266
267 <para>
268 pidl takes a different approach, and writes it like this:
269 </para>
270
271 <programlisting>
272     typedef struct {
273                 long abc;
274                 long count;     
275                 long foo;
276                 long *s;
277         } Struct1;
278 </programlisting>
279
280 </refsect2>
281
282 <refsect2>
283         <title>VARYING ARRAYS</title>
284
285 <para>
286 A varying array looks like this:
287 </para>
288
289 <programlisting>
290         typedef struct {
291                 long abc;
292                 long count;     
293                 long foo;
294                 [size_is(count)] long *s;
295         } Struct1;
296 </programlisting>
297
298 <para>
299 This will look like this on the wire:
300 </para>
301
302 <programlisting>
303 [abc] [count] [foo] [PTR_s]    [count] [s...]
304 </programlisting>
305
306 </refsect2>
307
308 <refsect2>
309         <title>FIXED ARRAYS</title>
310
311 <para>
312 A fixed array looks like this:
313 </para>
314
315 <programlisting>
316     typedef struct {
317             long s[10];
318     } Struct1;
319 </programlisting>
320
321 <para>
322 The NDR representation looks just like 10 separate long
323 declarations. The array size is not encoded on the wire.
324 </para>
325
326 <para>
327 pidl also supports "inline" arrays, which are not part of the IDL/NDR
328 standard. These are declared like this:
329 </para>
330
331 <programlisting>
332     typedef struct {
333             uint32 foo;
334             uint32 count;
335             uint32 bar;
336             long s[count];
337     } Struct1;
338 </programlisting>
339
340 <para>
341 This appears like this:
342 </para>
343
344 <programlisting>
345 [foo] [count] [bar] [s...]
346 </programlisting>
347
348 <para>
349 Fixed arrays are an extension added to support some of the strange
350 embedded structures in security descriptors and spoolss. 
351 </para>
352
353 </refsect2>
354
355 <para>This section is by no means complete. See the OpenGroup and MSDN 
356         documentation for additional information.</para>
357 </refsect1>
358
359 <refsect1>
360         <title>COMPATIBILITY WITH MIDL</title>
361
362         <refsect2>
363                 <title>Missing features in pidl</title>
364                 <para>
365                         The following MIDL features are not (yet) implemented in pidl 
366                         or are implemented with an incompatible interface:
367                 </para>
368
369                 <simplelist>
370                         <member>Asynchronous communication</member>
371                         <member>Typelibs (.tlb files)</member>
372                         <member>Datagram support (ncadg_*)</member>
373                 </simplelist>
374         </refsect2>
375
376         <refsect2>
377                 <title>Supported properties (attributes is the MIDL term)</title>
378
379                 <para>
380                         in, out, ref, length_is, switch_is, size_is, uuid, case, default, string, unique, ptr, pointer_default, v1_enum, object, helpstring, range, local, call_as, endpoint, switch_type, progid, coclass, iid_is.
381                 </para>
382
383 </refsect2>
384
385 <refsect2>
386         <title>PIDL Specific properties</title>
387
388 <variablelist>
389         <varlistentry><term>public</term>
390                 <listitem><para>
391 The [public] property on a structure or union is a pidl extension that
392 forces the generated pull/push functions to be non-static. This allows
393 you to declare types that can be used between modules. If you don't
394 specify [public] then pull/push functions for other than top-level
395 functions are declared static.
396                 </para></listitem>
397         </varlistentry>
398                                 
399         <varlistentry><term>noprint</term>
400                 <listitem><para>
401 The [noprint] property is a pidl extension that allows you to specify
402 that pidl should not generate a ndr_print_*() function for that
403 structure or union. This is used when you wish to define your own
404 print function that prints a structure in a nicer manner. A good
405 example is the use of [noprint] on dom_sid, which allows the
406 pretty-printing of SIDs.
407                 </para></listitem>
408         </varlistentry>
409
410         <varlistentry><term>value</term>
411                 <listitem><para>
412 The [value(expression)] property is a pidl extension that allows you
413 to specify the value of a field when it is put on the wire. This
414 allows fields that always have a well-known value to be automatically
415 filled in, thus making the API more programmer friendly. The
416 expression can be any C expression.
417                 </para></listitem>
418         </varlistentry>
419                 
420         <varlistentry><term>relative</term>
421                 <listitem><para>
422 The [relative] property can be supplied on a pointer. When it is used
423 it declares the pointer as a spoolss style "relative" pointer, which
424 means it appears on the wire as an offset within the current
425 encapsulating structure. This is not part of normal IDL/NDR, but it is
426 a very useful extension as it avoids the manual encoding of many
427 complex structures.
428                 </para></listitem>
429         </varlistentry>
430
431         <varlistentry><term>subcontext(length)</term>
432                 <listitem><para>
433                                 Specifies that a size of <replaceable>length</replaceable>
434                                 bytes should be read, followed by a blob of that size, 
435                                 which will be parsed as NDR.
436                 </para></listitem>
437         </varlistentry>
438
439         <varlistentry><term>flag</term>
440                 <listitem><para>
441                                 Specify boolean options, mostly used for 
442                                 low-level NDR options. Several options 
443                                 can be specified using the | character.
444                                 Note that flags are inherited by substructures!
445                 </para></listitem>
446         </varlistentry>
447
448         <varlistentry><term>nodiscriminant</term>
449                 <listitem><para>
450 The [nodiscriminant] property on a union means that the usual uint16
451 discriminent field at the start of the union on the wire is
452 omitted. This is not normally allowed in IDL/NDR, but is used for some
453 spoolss structures.
454                 </para></listitem>
455         </varlistentry>
456
457         <varlistentry><term>charset(name)</term>
458                 <listitem><para>
459                                 Specify that the array or string uses the specified 
460                                 charset. If this attribute is specified, pidl will 
461                                 take care of converting the character data from this format 
462                                 to the host format. Commonly used values are UCS2, DOS and UTF8.
463                 </para></listitem>
464         </varlistentry>
465 </variablelist>
466 </refsect2>
467
468 <refsect2>
469         <title>Unsupported MIDL properties</title>
470
471 <para>aggregatable, appobject, async_uuid, bindable, control, cpp_quote, defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface, displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext, helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib, import, include, includelib, last_is, lcid, licensed, max_is, module, ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl, oleautomation, optional, pragma, propget, propputref, propput, readonly, requestedit, restricted, retval, source, transmit_as, uidefault, usesgetlasterror, vararg, vi_progid, wire_marshal. </para>
472
473 </refsect2>
474
475 </refsect1>
476
477 <refsect1>
478         <title>ETHEREAL CONFORMANCE FILES</title>
479
480 <para>
481 Pidl needs additional data for ethereal output. This data is read from 
482 so-called conformance files. This section describes the format of these 
483 files.</para>
484
485 <para>
486 Conformance files are simple text files with a single command on each line.
487 Empty lines and lines starting with a '#' character are ignored.
488 Arguments to commands are seperated by spaces.
489 </para>
490
491 <para>
492 The following commands are currently supported:
493 </para>
494
495 <variablelist>
496
497 <varlistentry>
498         <term>TYPE name dissector ft_type base_type mask valsstring alignment</term>
499         <listitem><para>Register new data type with specified name, what dissector function to call and what properties to give header fields for elements of this type.</para></listitem>
500 </varlistentry>
501
502 <varlistentry>
503         <term>NOEMIT type</term>
504         <listitem><para>
505         Suppress emitting a dissect_type function for the specified type
506         </para></listitem>
507 </varlistentry>
508
509 <varlistentry>
510         <term>PARAM_VALUE type param</term>
511         <listitem><para>
512         Set parameter to specify to dissector function for given type.
513         </para></listitem>
514 </varlistentry>
515
516 <varlistentry>
517         <term>HF_FIELD hf title filter ft_type base_type valsstring mask description</term>
518         <listitem><para>
519         Generate a custom header field with specified properties.
520         </para></listitem>
521 </varlistentry>
522
523 <varlistentry>
524         <term>HF_RENAME old_hf_name new_hf_name</term>
525         <listitem><para>
526         Force the use of new_hf_name when the parser generator was going to 
527         use old_hf_name.
528         </para>
529
530         <para>
531         This can be used in conjunction with HF_FIELD in order to make more then 
532         one element use the same filter name.
533         </para>
534         </listitem>
535 </varlistentry>
536
537 <varlistentry>
538         <term>STRIP_PREFIX prefix</term>
539         <listitem><para>
540         Remove the specified prefix from all function names (if present).
541         </para></listitem>
542 </varlistentry>
543         
544 <varlistentry>
545         <term>PROTOCOL longname shortname filtername</term>
546         <listitem><para>
547         Change the short-, long- and filter-name for the current interface in
548         Ethereal.
549         </para></listitem>
550 </varlistentry>
551
552 <varlistentry>
553         <term>FIELD_DESCRIPTION field desc</term>
554         <listitem><para>Change description for the specified header field. `field' is the hf name of the field.
555         </para></listitem>
556 </varlistentry>
557
558 <varlistentry>
559         <term>IMPORT dissector code...</term>
560         <listitem><para>
561         Code to insert when generating the specified dissector. @HF@ and 
562         @PARAM@ will be substituted.
563         </para></listitem>
564 </varlistentry>
565
566 </variablelist>
567
568 </refsect1>
569
570 <refsect1>
571         <title>EXAMPLES</title>
572
573         <programlisting>
574         # Generating an ethereal parser
575         $ ./pidl --eth-parser -- atsvc.idl
576         
577         # Generating a TDR parser
578         $ ./pidl --tdr-parser --tdr-header --header -- regf.idl
579         </programlisting>
580
581 </refsect1>
582
583 <refsect1>
584         <title>VERSION</title>
585
586         <para>This man page is correct for version 4.0 of the Samba suite.</para>
587 </refsect1>
588
589 <refsect1>
590         <title>SEE ALSO</title>
591
592         <para><ulink url="http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp">Field Attributes [Remote Procedure Call]</ulink>, <ulink url="http://wiki.ethereal.com/DCE/RPC">Ethereal Wiki on DCE/RPC</ulink>.</para>
593
594 </refsect1>
595
596 <refsect1>
597         <title>AUTHOR</title>
598
599         <para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim 
600                 Potter and Jelmer Vernooij. </para>
601
602         <para>This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. </para>
603         
604 </refsect1>
605
606 </refentry>