From efc03df292aa84edb592c22191dbf86cdf8c32d0 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 21 Aug 2005 23:17:35 +0000 Subject: r9459: Move pidl up one level (to prevent too much nesting) (This used to be commit e48202275e60c18e464457d200daeb953386e221) --- source4/pidl/pidl.1.xml | 571 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 571 insertions(+) create mode 100644 source4/pidl/pidl.1.xml (limited to 'source4/pidl/pidl.1.xml') 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 @@ + + + + + + pidl + 1 + + + + pidl + IDL Compiler written in Perl + + + + + pidl + --help + --outputdir OUTNAME + --parse + --dump + --ndr-header[=OUTPUT] + --header[=OUTPUT] + --ejs[=OUTPUT] + --swig[=OUTPUT] + --uint-enums + --ndr-parser[=OUTPUT] + --client + --server + --dcom-proxy + --com-header + --odl + --warn-compat + --quiet + --verbose + --template + --eth-parser[=OUTPUT] + --diff + --keep + idlfile + idlfile2 + ... + + + + + DESCRIPTION + + pidl is an IDL compiler written in Perl that aims to be somewhat + compatible with the midl compiler. IDL stands for + "Interface Definition Language". + + pidl can generate stubs for DCE/RPC server code, DCE/RPC + client code and ethereal dissectors for DCE/RPC traffic. + + IDL compilers like pidl 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. + + 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. + + + + 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). + + + + + + OPTIONS + + + + --help + + Show list of available options. + + + + --outputdir OUTNAME + Write output files to the specified directory. + Defaults to the current directory. + + + + + --parse + + Tell pidl the files specified are (midl-style) IDL files. + + + + + --dump + + Convert .pidl files to (midl-style) IDL files. FIle will be named OUTNAME.idl. + + + + + --header + + Generate a C header file for the specified interface. Filename defaults to OUTNAME.h. + + + + --ndr-header + + Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h. + + + + --ndr-parser + + Generate a C file containing NDR parsers. + Filename defaults to ndr_OUTNAME.c. + + + + + + --server + + Generate boilerplate for the RPC server that implements + the interface. Filename defaults to ndr_OUTNAME_s.c + + + + + --template + + Generate stubs for a RPC server that implements + the interface. Output will be written to stdout. + + + + + + --eth-parser + + Generate an Ethereal dissector (in C) for the interface. Filename + defaults to packet-dcerpc-OUTNAME.c. + + + 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 + cnf rather then idl. See + below for details on the format of this file. + + + + + --diff + + 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. + + + + + --keep + + 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. + + + + + + IDL SYNTAX + + IDL files are always preprocessed using the C preprocessor. + + 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. + + See the section COMPATIBILITY for the list of attributes that + pidl supports. + + C-style comments can be used. + + + CONFORMANT ARRAYS + + +A conformant array is one with that ends in [*] or []. The strange +things about conformant arrays are: + + + + they can only appear as the last element of a structure + the array size appears before the structure itself on the wire. + + + + So, in this example: + + + + typedef struct { + long abc; + long count; + long foo; + [size_is(count)] long s[*]; + } Struct1; + + + +it appears like this: + + + +[size_is] [abc] [count] [foo] [s...] + + + +the first [size_is] field is the allocation size of the array, and +occurs before the array elements and even before the structure +alignment. + + + +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. + + + +midl.exe would write the above array as the following C header: + + + + typedef struct { + long abc; + long count; + long foo; + long s[1]; + } Struct1; + + + +pidl takes a different approach, and writes it like this: + + + + typedef struct { + long abc; + long count; + long foo; + long *s; + } Struct1; + + + + + + VARYING ARRAYS + + +A varying array looks like this: + + + + typedef struct { + long abc; + long count; + long foo; + [size_is(count)] long *s; + } Struct1; + + + +This will look like this on the wire: + + + +[abc] [count] [foo] [PTR_s] [count] [s...] + + + + + + FIXED ARRAYS + + +A fixed array looks like this: + + + + typedef struct { + long s[10]; + } Struct1; + + + +The NDR representation looks just like 10 separate long +declarations. The array size is not encoded on the wire. + + + +pidl also supports "inline" arrays, which are not part of the IDL/NDR +standard. These are declared like this: + + + + typedef struct { + uint32 foo; + uint32 count; + uint32 bar; + long s[count]; + } Struct1; + + + +This appears like this: + + + +[foo] [count] [bar] [s...] + + + +Fixed arrays are an extension added to support some of the strange +embedded structures in security descriptors and spoolss. + + + + +This section is by no means complete. See the OpenGroup and MSDN + documentation for additional information. + + + + COMPATIBILITY WITH MIDL + + + Asynchronous communication + + + + + + Typelibs (.tlb files) + + + + + + Datagram support + + ncadg is not supported yet. + + + + Supported properties (attributes is the MIDL term) + + +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. + + + + + + PIDL Specific properties + + + public + +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. + + + + noprint + +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. + + + + value + +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. + + + + relative + +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. + + + + subcontext(length) + + Specifies that a size of length + bytes should be read, followed by a blob of that size, + which will be parsed as NDR. + + + + flag + + 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! + + + + nodiscriminant + +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. + + + + charset(name) + + 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. + + + + + + + Unsupported MIDL properties + +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. + + + + + + + ETHEREAL CONFORMANCE FILES + + +Pidl needs additional data for ethereal output. This data is read from +so-called conformance files. This section describes the format of these +files. + + +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. + + + +The following commands are currently supported: + + + + + + TYPE name dissector ft_type base_type mask valsstring alignment + FIXME + + + + NOEMIT type + + Suppress emitting a dissect_type function for the specified type + + + + + PARAM_VALUE type param + + FIXME + + + + + HF_FIELD hf title filter ft_type base_type valsstring mask blurb + + FIXME + + + + + HF_RENAME old_hf_name new_hf_name + FIXME + + + + STRIP_PREFIX prefix + FIXME + + + + PROTOCOL longname shortname filtername + FIXME + + + + FIELD_DESCRIPTION field desc + FIXME + + + + IMPORT dissector code... + FIXME + + + + + + + + VERSION + + This man page is correct for version 4.0 of the Samba suite. + + + + SEE ALSO + + Field Attributes [Remote Procedure Call], Ethereal Wiki on DCE/RPC. + + + + + AUTHOR + + &man.credits.samba; + + pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim + Potter and Jelmer Vernooij. + + This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. + + + + -- cgit