r7117: Move more manpages to the source repository
[samba.git] / source / build / 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">--output OUTNAME</arg>
20                 <arg choice="opt">--parse</arg>
21                 <arg choice="opt">--dump</arg>
22                 <arg choice="opt">--header</arg>
23                 <arg choice="opt">--parser</arg>
24                 <arg choice="opt">--server</arg>
25                 <arg choice="opt">--template</arg>
26                 <arg choice="opt">--eth-parser</arg>
27                 <arg choice="opt">--eth-header</arg>
28                 <arg choice="opt">--diff</arg>
29                 <arg choice="opt">--keep</arg>
30                 <arg choice="req">idlfile</arg>
31         </cmdsynopsis>
32 </refsynopsisdiv>
33
34 <refsect1>
35         <title>DESCRIPTION</title>
36
37         <para>pidl is an IDL compiler written in Perl that aims to be somewhat 
38                 compatible with the midl compiler. IDL stands for 
39                 "Interface Definition Language".</para>
40
41         <para>pidl can generate stubs for DCE/RPC server code, DCE/RPC 
42                 client code and ethereal dissectors for DCE/RPC traffic.</para>
43
44         <para>IDL compilers like <emphasis>pidl</emphasis> take a description 
45                 of an interface as their input and use it to generate C 
46                 (though support for other languages may be added later) code that 
47                 can use these interfaces, pretty print data sent 
48                 using these interfaces, or even generate ethereal 
49                 dissectors that can parse data sent over the 
50                 wire by these interfaces. </para>
51
52         <para>pidl takes IDL files in the same format that is used by midl, 
53                 converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
54                 .pidl files should be used for debugging purposes only. Write your 
55                 interface definitions in (midl) .idl format.
56         </para>
57
58         <para>
59                 The goal of pidl is to implement a IDL compiler that can be used 
60                 while developing the RPC subsystem in Samba (for 
61                 both marshalling/un-marshalling and debugging purposes).</para>
62
63 </refsect1>
64
65 <refsect1>
66         <title>OPTIONS</title>
67
68         <variablelist>
69                 <varlistentry>
70                 <term>--help</term>
71                 <listitem><para>
72                 Show list of available options.</para></listitem>
73                 </varlistentry>
74                 
75                 <varlistentry>
76                 <term>--output OUTNAME</term>
77                 <listitem><para>Write output files to OUTNAME.*, e.g. 
78                                 OUTNAME.pidl. If --output is not used, the name of 
79                                 the input IDL file is used without the extension and the dot 
80                                 before the extension.
81                 </para></listitem>
82                 </varlistentry>
83                 
84                 <varlistentry>
85                 <term>--parse</term>
86                 <listitem><para>
87                                 Tell pidl the files specified are (midl-style) IDL files.</para></listitem>
88                 </varlistentry>
89
90
91                 <varlistentry>
92                 <term>--dump</term>
93                 <listitem><para>
94                                 Convert .pidl files to (midl-style) IDL files. FIle will be named OUTNAME.idl.</para></listitem>
95                 </varlistentry>
96
97
98                 <varlistentry>
99                 <term>--header</term>
100                 <listitem><para>
101                                 Generate a C header file for the specified interface. File will be named OUTNAME.h.</para></listitem>
102                 </varlistentry>
103
104
105                 <varlistentry>
106                 <term>--parser</term>
107                 <listitem><para>
108                                 Generate a C file capable of parsing data sent using the interface. 
109                                 File will be named OUTNAME.c.
110                 </para></listitem>
111                 </varlistentry>
112
113
114                 <varlistentry>
115                 <term>--server</term>
116                 <listitem><para>
117                 Generate boilerplate for the RPC server that implements 
118                 the interface. Generates OUTNAME_s.c</para></listitem>
119                 </varlistentry>
120
121
122                 <varlistentry>
123                 <term>--template</term>
124                 <listitem><para>
125                 Generate stubs for a RPC server that implements 
126                 the interface. Output will be written to stdout.
127                 </para></listitem>
128                 </varlistentry>
129
130
131                 <varlistentry>
132                 <term>--eth-parser</term>
133                 <listitem><para>
134                 Generate an Ethereal dissector (in C) for the interface. Output will 
135                 be written to packet-dcerpc-OUTNAME.c.
136                 </para></listitem>
137                 </varlistentry>
138
139                 <varlistentry>
140                 <term>--eth-header</term>
141                 <listitem><para>
142                 Generate a header file for the Ethereal dissector. Output will 
143                 be written to packet-dcerpc-OUTNAME.h.
144                 </para></listitem>
145                 </varlistentry>
146
147                 <varlistentry>
148                 <term>--diff</term>
149                 <listitem><para>
150                 Convert an IDL file to a pidl file and then back to a 
151                 IDL file and see if there are any differences with the 
152                 original IDL file. Useful for debugging pidl.</para></listitem>
153                 </varlistentry>
154
155
156                 <varlistentry>
157                 <term>--keep</term>
158                 <listitem><para>
159                 Tell pidl to keep the pidl files (used as intermediate files 
160                 between the IDL files and the parser/server/etc code). Useful 
161                 for debugging pidl.</para></listitem>
162                 </varlistentry>
163         </variablelist>
164 </refsect1>
165
166 <refsect1>
167         <title>SYNTAX</title>
168
169         <para>IDL files are always preprocessed using the C preprocessor.</para>
170
171         <para>Each IDL file describes exactly one interface. Interfaces 
172                 can contain several C-like function definitions.</para>
173
174         <para>Pretty much everything in an interface (the interface itself,
175                 functions, parameters) can have attributes (or properties 
176                 whatever name you give them). Attributes 
177                 always prepend the element they apply to and are surrounded 
178                 by square brackets ([]). Multiple attributes 
179                 are separated by comma's; arguments to attributes are 
180                 specified between parentheses. </para>
181
182         <para>See the section COMPATIBILITY for the list of attributes that 
183                 pidl supports.</para>
184
185         <para>C-style comments can be used.</para>
186         
187 </refsect1>
188
189 <refsect1>
190         <title>MIDL TYPES</title>
191
192 <para>
193 pidl uses slightly different types to midl by default. The following
194 defines in your MS IDL may make things easier to use the same IDL on
195 both platforms.
196 </para>
197
198 <programlisting>
199 #define unistr [string] wchar_t *
200 #define uint8 char
201 #define uint16 short
202 #define uint32 long
203 #define HYPER_T hyper
204 </programlisting>
205
206 <para>
207         Let's look at the multiple ways you can encode an array.
208 </para>
209
210 <refsect2>
211         <title>CONFORMANT ARRAYS</title>
212
213         <para>
214 A conformant array is one with that ends in [*] or []. The strange
215 things about conformant arrays are:
216 </para>
217
218 <simplelist>
219         <member>they can only appear as the last element of a structure</member>
220         <member>the array size appears before the structure itself on the wire. </member>
221 </simplelist>
222
223 <para>
224         So, in this example:
225 </para>
226
227 <programlisting>
228         typedef struct {
229                 long abc;
230                 long count;     
231                 long foo;
232                 [size_is(count)] long s[*];
233         } Struct1;
234 </programlisting>
235
236 <para>
237 it appears like this:
238 </para>
239
240 <programlisting>
241 [size_is] [abc] [count] [foo] [s...]
242 </programlisting>
243
244 <para>
245 the first [size_is] field is the allocation size of the array, and
246 occurs before the array elements and even before the structure
247 alignment.
248 </para>
249
250 <para>
251 Note that size_is() can refer to a constant, but that doesn't change
252 the wire representation. It does not make the array a fixed array.
253 </para>
254
255 <para>
256 midl.exe would write the above array as the following C header:
257 </para>
258
259 <programlisting>
260    typedef struct {
261                 long abc;
262                 long count;     
263                 long foo;
264                 long s[1];
265         } Struct1;
266 </programlisting>
267
268 <para>
269 pidl takes a different approach, and writes it like this:
270 </para>
271
272 <programlisting>
273     typedef struct {
274                 long abc;
275                 long count;     
276                 long foo;
277                 long *s;
278         } Struct1;
279 </programlisting>
280
281 </refsect2>
282
283 <refsect2>
284         <title>VARYING ARRAYS</title>
285
286
287 <para>
288 A varying array looks like this:
289 </para>
290
291 <programlisting>
292         typedef struct {
293                 long abc;
294                 long count;     
295                 long foo;
296                 [size_is(count)] long *s;
297         } Struct1;
298 </programlisting>
299
300 <para>
301 This will look like this on the wire:
302 </para>
303
304 <programlisting>
305 [abc] [count] [foo] [PTR_s]    [count] [s...]
306 </programlisting>
307
308 </refsect2>
309
310 <refsect2>
311         <title>FIXED ARRAYS</title>
312
313 <para>
314 A fixed array looks like this:
315 </para>
316
317 <programlisting>
318     typedef struct {
319             long s[10];
320     } Struct1;
321 </programlisting>
322
323 <para>
324 The NDR representation looks just like 10 separate long
325 declarations. The array size is not encoded on the wire.
326 </para>
327
328 <para>
329 pidl also supports "inline" arrays, which are not part of the IDL/NDR
330 standard. These are declared like this:
331 </para>
332
333 <programlisting>
334     typedef struct {
335             uint32 foo;
336             uint32 count;
337             uint32 bar;
338             long s[count];
339     } Struct1;
340 </programlisting>
341
342 <para>
343 This appears like this:
344 </para>
345
346 <programlisting>
347 [foo] [count] [bar] [s...]
348 </programlisting>
349
350 <para>
351 Fixed arrays are an extension added to support some of the strange
352 embedded structures in security descriptors and spoolss. 
353 </para>
354
355 </refsect2>
356 </refsect1>
357
358 <refsect1>
359         <title>COMPATIBILITY WITH MIDL</title>
360
361         <refsect2>
362                 <title>Asynchronous communication</title>
363
364                 <!--FIXME-->
365         </refsect2>
366
367         <refsect2>
368                 <title>Typelibs (.tlb files)</title>
369
370                 <!-- FIXME -->
371         </refsect2>
372
373         <refsect2>
374                 <title>strings</title>
375
376                 <para>Strings in pidl are a data type rather then an attribute.</para>
377                 <!--FIXME-->
378         </refsect2>
379
380         <refsect2>
381                 <title>Pointers</title>
382
383                 <para>Pidl does not support "full" pointers in the DCE meaning of the word. However, its "unique" pointer is compatible with MIDL's full ("ptr") pointer support. </para>
384         </refsect2>
385
386         <refsect2>
387                 <title>Datagram support</title>
388
389                 <para>ncadg is not supported yet.</para>
390         </refsect2>
391
392 <refsect2>
393         <title>Supported properties (attributes is the MIDL term)</title>
394
395         <para>
396 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.
397         </para>
398
399 </refsect2>
400
401 <refsect2>
402         <title>PIDL Specific properties</title>
403
404 <variablelist>
405         <varlistentry><term>public</term>
406                 <listitem><para>
407 The [public] property on a structure or union is a pidl extension that
408 forces the generated pull/push functions to be non-static. This allows
409 you to declare types that can be used between modules. If you don't
410 specify [public] then pull/push functions for other than top-level
411 functions are declared static.
412                 </para></listitem>
413         </varlistentry>
414                                 
415         <varlistentry><term>noprint</term>
416                 <listitem><para>
417 The [noprint] property is a pidl extension that allows you to specify
418 that pidl should not generate a ndr_print_*() function for that
419 structure or union. This is used when you wish to define your own
420 print function that prints a structure in a nicer manner. A good
421 example is the use of [noprint] on dom_sid, which allows the
422 pretty-printing of SIDs.
423                 </para></listitem>
424         </varlistentry>
425
426         <varlistentry><term>value</term>
427                 <listitem><para>
428 The [value(expression)] property is a pidl extension that allows you
429 to specify the value of a field when it is put on the wire. This
430 allows fields that always have a well-known value to be automatically
431 filled in, thus making the API more programmer friendly. The
432 expression can be any C expression, although if you refer to variables
433 in the current structure you will need to dereference them with
434 r->. See samr_Name as a good example.
435                 </para></listitem>
436         </varlistentry>
437                 
438         <varlistentry><term>relative</term>
439                 <listitem><para>
440 The [relative] property can be supplied on a pointer. When it is used
441 it declares the pointer as a spoolss style "relative" pointer, which
442 means it appears on the wire as an offset within the current
443 encapsulating structure. This is not part of normal IDL/NDR, but it is
444 a very useful extension as it avoids the manual encoding of many
445 complex structures.
446                 </para></listitem>
447         </varlistentry>
448
449         <varlistentry><term>subcontext(length)</term>
450                 <listitem><para>
451                                 Specifies that a size of <replaceable>length</replaceable>
452                                 bytes should be read, followed by a blob of that size, 
453                                 which will be parsed as NDR.
454                 </para></listitem>
455         </varlistentry>
456
457         <varlistentry><term>flag</term>
458                 <listitem><para>
459                                 Specify boolean options, mostly used for 
460                                 low-level NDR options. Several options 
461                                 can be specified using the | character.
462                                 Note that flags are inherited by substructures!
463                 </para></listitem>
464         </varlistentry>
465
466         <varlistentry><term>nodiscriminant</term>
467                 <listitem><para>
468 The [nodiscriminant] property on a union means that the usual uint16
469 discriminent field at the start of the union on the wire is
470 omitted. This is not normally allowed in IDL/NDR, but is used for some
471 spoolss structures.
472                 </para></listitem>
473         </varlistentry>
474
475         <varlistentry><term>align</term>
476                 <listitem><para>
477                                 Force the alignment of the field this attribute is placed 
478                                 on to the number of bytes specified.
479                 </para></listitem>
480         </varlistentry>
481 </variablelist>
482 </refsect2>
483
484 <refsect2>
485         <title>Unsupported MIDL properties</title>
486
487 <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>
488
489 </refsect2>
490
491 </refsect1>
492
493 <refsect1>
494         <title>VERSION</title>
495
496         <para>This man page is correct for version 4.0 of the Samba suite.</para>
497 </refsect1>
498
499 <refsect1>
500         <title>SEE ALSO</title>
501
502         <para><ulink url="http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp">Field Attributes [Remote Procedure Call]</ulink>, ethereal</para>
503
504 </refsect1>
505
506 <refsect1>
507         <title>AUTHOR</title>
508
509         &man.credits.samba;
510
511         <para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim 
512                 Potter and Jelmer Vernooij. </para>
513
514         <para>This manpage was written by Andrew Tridgell and Jelmer Vernooij. </para>
515         
516 </refsect1>
517
518 </refentry>