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