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">--outputdir OUTNAME</arg>
  20                 <arg choice="opt">--parse</arg>
  21                 <arg choice="opt">--dump</arg>
  22                 <arg choice="opt">--ndr-header[=OUTPUT]</arg>
  23                 <arg choice="opt">--header[=OUTPUT]</arg>
  24                 <arg choice="opt">--ejs[=OUTPUT]</arg>
  25                 <arg choice="opt">--swig[=OUTPUT]</arg>
  26                 <arg choice="opt">--uint-enums</arg>
  27                 <arg choice="opt">--ndr-parser[=OUTPUT]</arg>
  28                 <arg choice="opt">--client</arg>
  29                 <arg choice="opt">--server</arg>
  30                 <arg choice="opt">--dcom-proxy</arg>
  31                 <arg choice="opt">--com-header</arg>
  32                 <arg choice="opt">--odl</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">--keep</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</term>
  97                 <listitem><para>
  98                                 Tell pidl the files specified are (midl-style) IDL files.</para></listitem>
  99                 </varlistentry>
 100
 101
 102                 <varlistentry>
 103                 <term>--dump</term>
 104                 <listitem><para>
 105                                 Convert .pidl files to (midl-style) IDL files. FIle will be named OUTNAME.idl.</para></listitem>
 106                 </varlistentry>
 107
 108
 109                 <varlistentry>
 110                 <term>--header</term>
 111                 <listitem><para>
 112                                 Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.</para></listitem>
 113                 </varlistentry>
 114
 115                 <varlistentry>
 116                 <term>--ndr-header</term>
 117                 <listitem><para>
 118                                 Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.</para></listitem>
 119                 </varlistentry>
 120
 121                 <varlistentry>
 122                 <term>--ndr-parser</term>
 123                 <listitem><para>
 124                                 Generate a C file containing NDR parsers.
 125                                 Filename defaults to ndr_OUTNAME.c.
 126                 </para></listitem>
 127                 </varlistentry>
 128
 129
 130                 <varlistentry>
 131                 <term>--server</term>
 132                 <listitem><para>
 133                 Generate boilerplate for the RPC server that implements
 134                 the interface. Filename defaults to ndr_OUTNAME_s.c</para></listitem>
 135                 </varlistentry>
 136
 137
 138                 <varlistentry>
 139                 <term>--template</term>
 140                 <listitem><para>
 141                 Generate stubs for a RPC server that implements
 142                 the interface. Output will be written to stdout.
 143                 </para></listitem>
 144                 </varlistentry>
 145
 146
 147                 <varlistentry>
 148                 <term>--eth-parser</term>
 149                 <listitem><para>
 150                 Generate an Ethereal dissector (in C) for the interface. Filename
 151                 defaults to packet-dcerpc-OUTNAME.c.
 152                 </para>
 153
 154                 <para>Pidl will read additional data
 155                         from an ethereal conformance file if present. Such a file should
 156                         have the same location as the IDL file but with the extension
 157                         <quote>cnf</quote> rather then <quote>idl</quote>. See
 158                         below for details on the format of this file.
 159                 </para></listitem>
 160                 </varlistentry>
 161
 162                 <varlistentry>
 163                 <term>--diff</term>
 164                 <listitem><para>
 165                 Convert an IDL file to a pidl file and then back to a
 166                 IDL file and see if there are any differences with the
 167                 original IDL file. Useful for debugging pidl.</para></listitem>
 168                 </varlistentry>
 169
 170
 171                 <varlistentry>
 172                 <term>--keep</term>
 173                 <listitem><para>
 174                 Tell pidl to keep the pidl files (used as intermediate files
 175                 between the IDL files and the parser/server/etc code). Useful
 176                 for debugging pidl.</para></listitem>
 177                 </varlistentry>
 178         </variablelist>
 179 </refsect1>
 180
 181 <refsect1>
 182         <title>IDL SYNTAX</title>
 183
 184         <para>IDL files are always preprocessed using the C preprocessor.</para>
 185
 186         <para>Pretty much everything in an interface (the interface itself,
 187                 functions, parameters) can have attributes (or properties
 188                 whatever name you give them). Attributes
 189                 always prepend the element they apply to and are surrounded
 190                 by square brackets ([]). Multiple attributes
 191                 are separated by comma's; arguments to attributes are
 192                 specified between parentheses. </para>
 193
 194         <para>See the section COMPATIBILITY for the list of attributes that
 195                 pidl supports.</para>
 196
 197         <para>C-style comments can be used.</para>
 198
 199 <refsect2>
 200         <title>CONFORMANT ARRAYS</title>
 201
 202         <para>
 203 A conformant array is one with that ends in [*] or []. The strange
 204 things about conformant arrays are:
 205 </para>
 206
 207 <simplelist>
 208         <member>they can only appear as the last element of a structure</member>
 209         <member>the array size appears before the structure itself on the wire. </member>
 210 </simplelist>
 211
 212 <para>
 213         So, in this example:
 214 </para>
 215
 216 <programlisting>
 217         typedef struct {
 218                 long abc;
 219                 long count;
 220                 long foo;
 221                 [size_is(count)] long s[*];
 222         } Struct1;
 223 </programlisting>
 224
 225 <para>
 226 it appears like this:
 227 </para>
 228
 229 <programlisting>
 230 [size_is] [abc] [count] [foo] [s...]
 231 </programlisting>
 232
 233 <para>
 234 the first [size_is] field is the allocation size of the array, and
 235 occurs before the array elements and even before the structure
 236 alignment.
 237 </para>
 238
 239 <para>
 240 Note that size_is() can refer to a constant, but that doesn't change
 241 the wire representation. It does not make the array a fixed array.
 242 </para>
 243
 244 <para>
 245 midl.exe would write the above array as the following C header:
 246 </para>
 247
 248 <programlisting>
 249    typedef struct {
 250                 long abc;
 251                 long count;
 252                 long foo;
 253                 long s[1];
 254         } Struct1;
 255 </programlisting>
 256
 257 <para>
 258 pidl takes a different approach, and writes it like this:
 259 </para>
 260
 261 <programlisting>
 262     typedef struct {
 263                 long abc;
 264                 long count;
 265                 long foo;
 266                 long *s;
 267         } Struct1;
 268 </programlisting>
 269
 270 </refsect2>
 271
 272 <refsect2>
 273         <title>VARYING ARRAYS</title>
 274
 275 <para>
 276 A varying array looks like this:
 277 </para>
 278
 279 <programlisting>
 280         typedef struct {
 281                 long abc;
 282                 long count;
 283                 long foo;
 284                 [size_is(count)] long *s;
 285         } Struct1;
 286 </programlisting>
 287
 288 <para>
 289 This will look like this on the wire:
 290 </para>
 291
 292 <programlisting>
 293 [abc] [count] [foo] [PTR_s]    [count] [s...]
 294 </programlisting>
 295
 296 </refsect2>
 297
 298 <refsect2>
 299         <title>FIXED ARRAYS</title>
 300
 301 <para>
 302 A fixed array looks like this:
 303 </para>
 304
 305 <programlisting>
 306     typedef struct {
 307             long s[10];
 308     } Struct1;
 309 </programlisting>
 310
 311 <para>
 312 The NDR representation looks just like 10 separate long
 313 declarations. The array size is not encoded on the wire.
 314 </para>
 315
 316 <para>
 317 pidl also supports "inline" arrays, which are not part of the IDL/NDR
 318 standard. These are declared like this:
 319 </para>
 320
 321 <programlisting>
 322     typedef struct {
 323             uint32 foo;
 324             uint32 count;
 325             uint32 bar;
 326             long s[count];
 327     } Struct1;
 328 </programlisting>
 329
 330 <para>
 331 This appears like this:
 332 </para>
 333
 334 <programlisting>
 335 [foo] [count] [bar] [s...]
 336 </programlisting>
 337
 338 <para>
 339 Fixed arrays are an extension added to support some of the strange
 340 embedded structures in security descriptors and spoolss.
 341 </para>
 342
 343 </refsect2>
 344
 345 <para>This section is by no means complete. See the OpenGroup and MSDN
 346         documentation for additional information.</para>
 347 </refsect1>
 348
 349 <refsect1>
 350         <title>COMPATIBILITY WITH MIDL</title>
 351
 352         <refsect2>
 353                 <title>Asynchronous communication</title>
 354
 355                 <!--FIXME-->
 356         </refsect2>
 357
 358         <refsect2>
 359                 <title>Typelibs (.tlb files)</title>
 360
 361                 <!-- FIXME -->
 362         </refsect2>
 363
 364         <refsect2>
 365                 <title>Datagram support</title>
 366
 367                 <para>ncadg is not supported yet.</para>
 368         </refsect2>
 369
 370 <refsect2>
 371         <title>Supported properties (attributes is the MIDL term)</title>
 372
 373         <para>
 374 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.
 375         </para>
 376
 377 </refsect2>
 378
 379 <refsect2>
 380         <title>PIDL Specific properties</title>
 381
 382 <variablelist>
 383         <varlistentry><term>public</term>
 384                 <listitem><para>
 385 The [public] property on a structure or union is a pidl extension that
 386 forces the generated pull/push functions to be non-static. This allows
 387 you to declare types that can be used between modules. If you don't
 388 specify [public] then pull/push functions for other than top-level
 389 functions are declared static.
 390                 </para></listitem>
 391         </varlistentry>
 392
 393         <varlistentry><term>noprint</term>
 394                 <listitem><para>
 395 The [noprint] property is a pidl extension that allows you to specify
 396 that pidl should not generate a ndr_print_*() function for that
 397 structure or union. This is used when you wish to define your own
 398 print function that prints a structure in a nicer manner. A good
 399 example is the use of [noprint] on dom_sid, which allows the
 400 pretty-printing of SIDs.
 401                 </para></listitem>
 402         </varlistentry>
 403
 404         <varlistentry><term>value</term>
 405                 <listitem><para>
 406 The [value(expression)] property is a pidl extension that allows you
 407 to specify the value of a field when it is put on the wire. This
 408 allows fields that always have a well-known value to be automatically
 409 filled in, thus making the API more programmer friendly. The
 410 expression can be any C expression.
 411                 </para></listitem>
 412         </varlistentry>
 413
 414         <varlistentry><term>relative</term>
 415                 <listitem><para>
 416 The [relative] property can be supplied on a pointer. When it is used
 417 it declares the pointer as a spoolss style "relative" pointer, which
 418 means it appears on the wire as an offset within the current
 419 encapsulating structure. This is not part of normal IDL/NDR, but it is
 420 a very useful extension as it avoids the manual encoding of many
 421 complex structures.
 422                 </para></listitem>
 423         </varlistentry>
 424
 425         <varlistentry><term>subcontext(length)</term>
 426                 <listitem><para>
 427                                 Specifies that a size of <replaceable>length</replaceable>
 428                                 bytes should be read, followed by a blob of that size,
 429                                 which will be parsed as NDR.
 430                 </para></listitem>
 431         </varlistentry>
 432
 433         <varlistentry><term>flag</term>
 434                 <listitem><para>
 435                                 Specify boolean options, mostly used for
 436                                 low-level NDR options. Several options
 437                                 can be specified using the | character.
 438                                 Note that flags are inherited by substructures!
 439                 </para></listitem>
 440         </varlistentry>
 441
 442         <varlistentry><term>nodiscriminant</term>
 443                 <listitem><para>
 444 The [nodiscriminant] property on a union means that the usual uint16
 445 discriminent field at the start of the union on the wire is
 446 omitted. This is not normally allowed in IDL/NDR, but is used for some
 447 spoolss structures.
 448                 </para></listitem>
 449         </varlistentry>
 450
 451         <varlistentry><term>charset(name)</term>
 452                 <listitem><para>
 453                                 Specify that the array or string uses the specified
 454                                 charset. If this attribute is specified, pidl will
 455                                 take care of converting the character data from this format
 456                                 to the host format. Commonly used values are UCS2, DOS and UTF8.
 457                 </para></listitem>
 458         </varlistentry>
 459 </variablelist>
 460 </refsect2>
 461
 462 <refsect2>
 463         <title>Unsupported MIDL properties</title>
 464
 465 <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>
 466
 467 </refsect2>
 468
 469 </refsect1>
 470
 471 <refsect1>
 472         <title>ETHEREAL CONFORMANCE FILES</title>
 473
 474 <para>
 475 Pidl needs additional data for ethereal output. This data is read from
 476 so-called conformance files. This section describes the format of these
 477 files.</para>
 478
 479 <para>
 480 Conformance files are simple text files with a single command on each line.
 481 Empty lines and lines starting with a '#' character are ignored.
 482 Arguments to commands are seperated by spaces.
 483 </para>
 484
 485 <para>
 486 The following commands are currently supported:
 487 </para>
 488
 489 <variablelist>
 490
 491 <varlistentry>
 492         <term>TYPE name dissector ft_type base_type mask valsstring alignment</term>
 493         <listitem><para>FIXME</para></listitem>
 494 </varlistentry>
 495
 496 <varlistentry>
 497         <term>NOEMIT type</term>
 498         <listitem><para>
 499                         Suppress emitting a dissect_type function for the specified type
 500         </para></listitem>
 501 </varlistentry>
 502
 503 <varlistentry>
 504         <term>PARAM_VALUE type param</term>
 505         <listitem><para>
 506                 FIXME
 507         </para></listitem>
 508 </varlistentry>
 509
 510 <varlistentry>
 511         <term>HF_FIELD hf title filter ft_type base_type valsstring mask blurb</term>
 512         <listitem><para>
 513         FIXME
 514         </para></listitem>
 515 </varlistentry>
 516
 517 <varlistentry>
 518         <term>HF_RENAME old_hf_name new_hf_name</term>
 519         <listitem><para>FIXME</para></listitem>
 520 </varlistentry>
 521
 522 <varlistentry>
 523         <term>STRIP_PREFIX prefix</term>
 524         <listitem><para>        FIXME</para></listitem>
 525 </varlistentry>
 526
 527 <varlistentry>
 528         <term>PROTOCOL longname shortname filtername</term>
 529         <listitem><para>FIXME</para></listitem>
 530 </varlistentry>
 531
 532 <varlistentry>
 533         <term>FIELD_DESCRIPTION field desc</term>
 534         <listitem><para>FIXME</para></listitem>
 535 </varlistentry>
 536
 537 <varlistentry>
 538         <term>IMPORT dissector code...</term>
 539         <listitem><para>FIXME</para></listitem>
 540 </varlistentry>
 541
 542 </variablelist>
 543
 544 </refsect1>
 545
 546 <refsect1>
 547         <title>VERSION</title>
 548
 549         <para>This man page is correct for version 4.0 of the Samba suite.</para>
 550 </refsect1>
 551
 552 <refsect1>
 553         <title>SEE ALSO</title>
 554
 555         <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>
 556
 557 </refsect1>
 558
 559 <refsect1>
 560         <title>AUTHOR</title>
 561
 562         &man.credits.samba;
 563
 564         <para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim
 565                 Potter and Jelmer Vernooij. </para>
 566
 567         <para>This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. </para>
 568
 569 </refsect1>
 570
 571 </refentry>