r9459: Move pidl up one level (to prevent too much nesting)

(This used to be commit e48202275e60c18e464457d200daeb953386e221)

1 files changed, 571 insertions, 0 deletions

diff --git a/source4/pidl/pidl.1.xml b/source4/pidl/pidl.1.xml
new file mode 100644
index 0000000000..cf7f560f0d
--- /dev/null
+++ b/source4/pidl/pidl.1.xml
@@ -0,0 +1,571 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="pidl.1">
+
+<refmeta>
+	<refentrytitle>pidl</refentrytitle>
+	<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+	<refname>pidl</refname>
+	<refpurpose>IDL Compiler written in Perl</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>pidl</command>
+		<arg choice="opt">--help</arg>
+		<arg choice="opt">--outputdir OUTNAME</arg>
+		<arg choice="opt">--parse</arg>
+		<arg choice="opt">--dump</arg>
+		<arg choice="opt">--ndr-header[=OUTPUT]</arg>
+		<arg choice="opt">--header[=OUTPUT]</arg>
+		<arg choice="opt">--ejs[=OUTPUT]</arg>
+		<arg choice="opt">--swig[=OUTPUT]</arg>
+		<arg choice="opt">--uint-enums</arg>
+		<arg choice="opt">--ndr-parser[=OUTPUT]</arg>
+		<arg choice="opt">--client</arg>
+		<arg choice="opt">--server</arg>
+		<arg choice="opt">--dcom-proxy</arg>
+		<arg choice="opt">--com-header</arg>
+		<arg choice="opt">--odl</arg>
+		<arg choice="opt">--warn-compat</arg>
+		<arg choice="opt">--quiet</arg>
+		<arg choice="opt">--verbose</arg>
+		<arg choice="opt">--template</arg>
+		<arg choice="opt">--eth-parser[=OUTPUT]</arg>
+		<arg choice="opt">--diff</arg>
+		<arg choice="opt">--keep</arg>
+		<arg choice="req">idlfile</arg>
+		<arg choice="opt">idlfile2</arg>
+		<arg choice="opt">...</arg>
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+
+	<para>pidl is an IDL compiler written in Perl that aims to be somewhat 
+		compatible with the midl compiler. IDL stands for 
+		"Interface Definition Language".</para>
+
+	<para>pidl can generate stubs for DCE/RPC server code, DCE/RPC 
+		client code and ethereal dissectors for DCE/RPC traffic.</para>
+
+	<para>IDL compilers like <emphasis>pidl</emphasis> take a description 
+		of an interface as their input and use it to generate C 
+		(though support for other languages may be added later) code that 
+		can use these interfaces, pretty print data sent 
+		using these interfaces, or even generate ethereal 
+		dissectors that can parse data sent over the 
+		wire by these interfaces. </para>
+
+	<para>pidl takes IDL files in the same format as is used by midl, 
+		converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
+		.pidl files should be used for debugging purposes only. Write your 
+		interface definitions in .idl format.
+	</para>
+
+	<para>
+		The goal of pidl is to implement a IDL compiler that can be used 
+		while developing the RPC subsystem in Samba (for 
+		both marshalling/unmarshalling and debugging purposes).
+	</para>
+
+</refsect1>
+
+<refsect1>
+	<title>OPTIONS</title>
+
+	<variablelist>
+		<varlistentry>
+		<term>--help</term>
+		<listitem><para>
+		Show list of available options.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>--outputdir OUTNAME</term>
+		<listitem><para>Write output files to the specified directory. 
+				Defaults to the current directory.
+		</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>--parse</term>
+		<listitem><para>
+				Tell pidl the files specified are (midl-style) IDL files.</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--dump</term>
+		<listitem><para>
+				Convert .pidl files to (midl-style) IDL files. FIle will be named OUTNAME.idl.</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--header</term>
+		<listitem><para>
+				Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--ndr-header</term>
+		<listitem><para>
+				Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--ndr-parser</term>
+		<listitem><para>
+				Generate a C file containing NDR parsers. 
+				Filename defaults to ndr_OUTNAME.c.
+		</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--server</term>
+		<listitem><para>
+		Generate boilerplate for the RPC server that implements 
+		the interface. Filename defaults to ndr_OUTNAME_s.c</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--template</term>
+		<listitem><para>
+		Generate stubs for a RPC server that implements 
+		the interface. Output will be written to stdout.
+		</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--eth-parser</term>
+		<listitem><para>
+		Generate an Ethereal dissector (in C) for the interface. Filename
+		defaults to packet-dcerpc-OUTNAME.c. 
+		</para>
+	
+		<para>Pidl will read additional data 
+			from an ethereal conformance file if present. Such a file should 
+			have the same location as the IDL file but with the extension 
+			<quote>cnf</quote> rather then <quote>idl</quote>. See 
+			below for details on the format of this file.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--diff</term>
+		<listitem><para>
+		Convert an IDL file to a pidl file and then back to a 
+		IDL file and see if there are any differences with the 
+		original IDL file. Useful for debugging pidl.</para></listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>--keep</term>
+		<listitem><para>
+		Tell pidl to keep the pidl files (used as intermediate files 
+		between the IDL files and the parser/server/etc code). Useful 
+		for debugging pidl.</para></listitem>
+		</varlistentry>
+	</variablelist>
+</refsect1>
+
+<refsect1>
+	<title>IDL SYNTAX</title>
+
+	<para>IDL files are always preprocessed using the C preprocessor.</para>
+
+	<para>Pretty much everything in an interface (the interface itself,
+		functions, parameters) can have attributes (or properties 
+		whatever name you give them). Attributes 
+		always prepend the element they apply to and are surrounded 
+		by square brackets ([]). Multiple attributes 
+		are separated by comma's; arguments to attributes are 
+		specified between parentheses. </para>
+
+	<para>See the section COMPATIBILITY for the list of attributes that 
+		pidl supports.</para>
+
+	<para>C-style comments can be used.</para>
+	
+<refsect2>
+	<title>CONFORMANT ARRAYS</title>
+
+	<para>
+A conformant array is one with that ends in [*] or []. The strange
+things about conformant arrays are:
+</para>
+
+<simplelist>
+	<member>they can only appear as the last element of a structure</member>
+	<member>the array size appears before the structure itself on the wire. </member>
+</simplelist>
+
+<para>
+	So, in this example:
+</para>
+
+<programlisting>
+	typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		[size_is(count)] long s[*];
+	} Struct1;
+</programlisting>
+
+<para>
+it appears like this:
+</para>
+
+<programlisting>
+[size_is] [abc] [count] [foo] [s...]
+</programlisting>
+
+<para>
+the first [size_is] field is the allocation size of the array, and
+occurs before the array elements and even before the structure
+alignment.
+</para>
+
+<para>
+Note that size_is() can refer to a constant, but that doesn't change
+the wire representation. It does not make the array a fixed array.
+</para>
+
+<para>
+midl.exe would write the above array as the following C header:
+</para>
+
+<programlisting>
+   typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		long s[1];
+	} Struct1;
+</programlisting>
+
+<para>
+pidl takes a different approach, and writes it like this:
+</para>
+
+<programlisting>
+    typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		long *s;
+	} Struct1;
+</programlisting>
+
+</refsect2>
+
+<refsect2>
+	<title>VARYING ARRAYS</title>
+
+<para>
+A varying array looks like this:
+</para>
+
+<programlisting>
+	typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		[size_is(count)] long *s;
+	} Struct1;
+</programlisting>
+
+<para>
+This will look like this on the wire:
+</para>
+
+<programlisting>
+[abc] [count] [foo] [PTR_s]    [count] [s...]
+</programlisting>
+
+</refsect2>
+
+<refsect2>
+	<title>FIXED ARRAYS</title>
+
+<para>
+A fixed array looks like this:
+</para>
+
+<programlisting>
+    typedef struct {
+	    long s[10];
+    } Struct1;
+</programlisting>
+
+<para>
+The NDR representation looks just like 10 separate long
+declarations. The array size is not encoded on the wire.
+</para>
+
+<para>
+pidl also supports "inline" arrays, which are not part of the IDL/NDR
+standard. These are declared like this:
+</para>
+
+<programlisting>
+    typedef struct {
+	    uint32 foo;
+	    uint32 count;
+	    uint32 bar;
+	    long s[count];
+    } Struct1;
+</programlisting>
+
+<para>
+This appears like this:
+</para>
+
+<programlisting>
+[foo] [count] [bar] [s...]
+</programlisting>
+
+<para>
+Fixed arrays are an extension added to support some of the strange
+embedded structures in security descriptors and spoolss. 
+</para>
+
+</refsect2>
+
+<para>This section is by no means complete. See the OpenGroup and MSDN 
+	documentation for additional information.</para>
+</refsect1>
+
+<refsect1>
+	<title>COMPATIBILITY WITH MIDL</title>
+
+	<refsect2>
+		<title>Asynchronous communication</title>
+
+		<!--FIXME-->
+	</refsect2>
+
+	<refsect2>
+		<title>Typelibs (.tlb files)</title>
+
+		<!-- FIXME -->
+	</refsect2>
+
+	<refsect2>
+		<title>Datagram support</title>
+
+		<para>ncadg is not supported yet.</para>
+	</refsect2>
+
+<refsect2>
+	<title>Supported properties (attributes is the MIDL term)</title>
+
+	<para>
+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.
+	</para>
+
+</refsect2>
+
+<refsect2>
+	<title>PIDL Specific properties</title>
+
+<variablelist>
+	<varlistentry><term>public</term>
+		<listitem><para>
+The [public] property on a structure or union is a pidl extension that
+forces the generated pull/push functions to be non-static. This allows
+you to declare types that can be used between modules. If you don't
+specify [public] then pull/push functions for other than top-level
+functions are declared static.
+		</para></listitem>
+	</varlistentry>
+				
+	<varlistentry><term>noprint</term>
+		<listitem><para>
+The [noprint] property is a pidl extension that allows you to specify
+that pidl should not generate a ndr_print_*() function for that
+structure or union. This is used when you wish to define your own
+print function that prints a structure in a nicer manner. A good
+example is the use of [noprint] on dom_sid, which allows the
+pretty-printing of SIDs.
+		</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term>value</term>
+		<listitem><para>
+The [value(expression)] property is a pidl extension that allows you
+to specify the value of a field when it is put on the wire. This
+allows fields that always have a well-known value to be automatically
+filled in, thus making the API more programmer friendly. The
+expression can be any C expression.
+		</para></listitem>
+	</varlistentry>
+		
+	<varlistentry><term>relative</term>
+		<listitem><para>
+The [relative] property can be supplied on a pointer. When it is used
+it declares the pointer as a spoolss style "relative" pointer, which
+means it appears on the wire as an offset within the current
+encapsulating structure. This is not part of normal IDL/NDR, but it is
+a very useful extension as it avoids the manual encoding of many
+complex structures.
+		</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term>subcontext(length)</term>
+		<listitem><para>
+				Specifies that a size of <replaceable>length</replaceable>
+				bytes should be read, followed by a blob of that size, 
+				which will be parsed as NDR.
+		</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term>flag</term>
+		<listitem><para>
+				Specify boolean options, mostly used for 
+				low-level NDR options. Several options 
+				can be specified using the | character.
+				Note that flags are inherited by substructures!
+		</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term>nodiscriminant</term>
+		<listitem><para>
+The [nodiscriminant] property on a union means that the usual uint16
+discriminent field at the start of the union on the wire is
+omitted. This is not normally allowed in IDL/NDR, but is used for some
+spoolss structures.
+		</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term>charset(name)</term>
+		<listitem><para>
+				Specify that the array or string uses the specified 
+				charset. If this attribute is specified, pidl will 
+				take care of converting the character data from this format 
+				to the host format. Commonly used values are UCS2, DOS and UTF8.
+		</para></listitem>
+	</varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2>
+	<title>Unsupported MIDL properties</title>
+
+<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>
+
+</refsect2>
+
+</refsect1>
+
+<refsect1>
+	<title>ETHEREAL CONFORMANCE FILES</title>
+
+<para>
+Pidl needs additional data for ethereal output. This data is read from 
+so-called conformance files. This section describes the format of these 
+files.</para>
+
+<para>
+Conformance files are simple text files with a single command on each line.
+Empty lines and lines starting with a '#' character are ignored.
+Arguments to commands are seperated by spaces.
+</para>
+
+<para>
+The following commands are currently supported:
+</para>
+
+<variablelist>
+
+<varlistentry>
+	<term>TYPE name dissector ft_type base_type mask valsstring alignment</term>
+	<listitem><para>FIXME</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>NOEMIT type</term>
+	<listitem><para>
+			Suppress emitting a dissect_type function for the specified type
+	</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>PARAM_VALUE type param</term>
+	<listitem><para>
+		FIXME
+	</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>HF_FIELD hf title filter ft_type base_type valsstring mask blurb</term>
+	<listitem><para>
+	FIXME
+	</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>HF_RENAME old_hf_name new_hf_name</term>
+	<listitem><para>FIXME</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>STRIP_PREFIX prefix</term>
+	<listitem><para>	FIXME</para></listitem>
+</varlistentry>
+	
+<varlistentry>
+	<term>PROTOCOL longname shortname filtername</term>
+	<listitem><para>FIXME</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>FIELD_DESCRIPTION field desc</term>
+	<listitem><para>FIXME</para></listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>IMPORT dissector code...</term>
+	<listitem><para>FIXME</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is correct for version 4.0 of the Samba suite.</para>
+</refsect1>
+
+<refsect1>
+	<title>SEE ALSO</title>
+
+	<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>
+
+</refsect1>
+
+<refsect1>
+	<title>AUTHOR</title>
+
+	&man.credits.samba;
+
+	<para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim 
+		Potter and Jelmer Vernooij. </para>
+
+	<para>This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. </para>
+	
+</refsect1>
+
+</refentry>