New version of pidl
This commit is contained in:
Wilco Baan Hofman
parent
d595112e01
commit
2186300bd2
74 changed files with 23043 additions and 988 deletions
0
bin/pidl/blib/man1/.exists
Normal file
0
bin/pidl/blib/man1/.exists
Normal file
424
bin/pidl/blib/man1/pidl.1p
Normal file
424
bin/pidl/blib/man1/pidl.1p
Normal file
|
|
@ -0,0 +1,424 @@
|
|||
.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ========================================================================
|
||||
.de Sp \" Vertical space (when we can't use .PP)
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Vb \" Begin verbatim text
|
||||
.ft CW
|
||||
.nf
|
||||
.ne \\$1
|
||||
..
|
||||
.de Ve \" End verbatim text
|
||||
.ft R
|
||||
.fi
|
||||
..
|
||||
.\" Set up some character translations and predefined strings. \*(-- will
|
||||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||||
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||||
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||||
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||||
.\" nothing in troff, for use with C<>.
|
||||
.tr \(*W-
|
||||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||||
.ie n \{\
|
||||
. ds -- \(*W-
|
||||
. ds PI pi
|
||||
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||||
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||||
. ds L" ""
|
||||
. ds R" ""
|
||||
. ds C` ""
|
||||
. ds C' ""
|
||||
'br\}
|
||||
.el\{\
|
||||
. ds -- \|\(em\|
|
||||
. ds PI \(*p
|
||||
. ds L" ``
|
||||
. ds R" ''
|
||||
. ds C`
|
||||
. ds C'
|
||||
'br\}
|
||||
.\"
|
||||
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.\"
|
||||
.\" If the F register is >0, we'll generate index entries on stderr for
|
||||
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||||
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||||
.\" output yourself in some meaningful fashion.
|
||||
.\"
|
||||
.\" Avoid warning from groff about undefined register 'F'.
|
||||
.de IX
|
||||
..
|
||||
.if !\nF .nr F 0
|
||||
.if \nF>0 \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
..
|
||||
. if !\nF==2 \{\
|
||||
. nr % 0
|
||||
. nr F 2
|
||||
. \}
|
||||
.\}
|
||||
.\" ========================================================================
|
||||
.\"
|
||||
.IX Title "PIDL 1p"
|
||||
.TH PIDL 1p "2016-11-15" "perl v5.24.1" "User Contributed Perl Documentation"
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||||
.\" way too many mistakes in technical documents.
|
||||
.if n .ad l
|
||||
.nh
|
||||
.SH "NAME"
|
||||
pidl \- An IDL compiler written in Perl
|
||||
.SH "SYNOPSIS"
|
||||
.IX Header "SYNOPSIS"
|
||||
pidl \-\-help
|
||||
.PP
|
||||
pidl [\-\-outputdir[=OUTNAME]] [\-\-includedir \s-1DIR...\s0] [\-\-parse\-idl\-tree] [\-\-dump\-idl\-tree] [\-\-dump\-ndr\-tree] [\-\-header[=OUTPUT]] [\-\-python[=OUTPUT]] [\-\-ndr\-parser[=OUTPUT]] [\-\-client] [\-\-server] [\-\-warn\-compat] [\-\-quiet] [\-\-verbose] [\-\-template] [\-\-ws\-parser[=OUTPUT]] [\-\-diff] [\-\-dump\-idl] [\-\-tdr\-parser[=OUTPUT]] [\-\-samba3\-ndr\-client[=OUTPUT]] [\-\-samba3\-ndr\-server[=OUTPUT]] [\-\-typelib=[\s-1OUTPUT\s0]] [<idlfile>.idl]...
|
||||
.SH "DESCRIPTION"
|
||||
.IX Header "DESCRIPTION"
|
||||
pidl is an \s-1IDL\s0 compiler written in Perl that aims to be somewhat
|
||||
compatible with the midl compiler. \s-1IDL\s0 is short for
|
||||
\&\*(L"Interface Definition Language\*(R".
|
||||
.PP
|
||||
pidl can generate stubs for \s-1DCE/RPC\s0 server code, \s-1DCE/RPC\s0
|
||||
client code and Wireshark dissectors for \s-1DCE/RPC\s0 traffic.
|
||||
.PP
|
||||
\&\s-1IDL\s0 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 Wireshark
|
||||
dissectors that can parse data sent over the
|
||||
wire by these interfaces.
|
||||
.PP
|
||||
pidl takes \s-1IDL\s0 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.
|
||||
.PP
|
||||
The goal of pidl is to implement a \s-1IDL\s0 compiler that can be used
|
||||
while developing the \s-1RPC\s0 subsystem in Samba (for
|
||||
both marshalling/unmarshalling and debugging purposes).
|
||||
.SH "OPTIONS"
|
||||
.IX Header "OPTIONS"
|
||||
.IP "\fI\-\-help\fR" 4
|
||||
.IX Item "--help"
|
||||
Show list of available options.
|
||||
.IP "\fI\-\-version\fR" 4
|
||||
.IX Item "--version"
|
||||
Show pidl version
|
||||
.IP "\fI\-\-outputdir \s-1OUTNAME\s0\fR" 4
|
||||
.IX Item "--outputdir OUTNAME"
|
||||
Write output files to the specified directory. Defaults to the current
|
||||
directory.
|
||||
.IP "\fI\-\-includedir \s-1DIR\s0\fR" 4
|
||||
.IX Item "--includedir DIR"
|
||||
Add \s-1DIR\s0 to the search path used by the preprocessor. This option can be
|
||||
specified multiple times.
|
||||
.IP "\fI\-\-parse\-idl\-tree\fR" 4
|
||||
.IX Item "--parse-idl-tree"
|
||||
Read internal tree structure from input files rather
|
||||
than assuming they contain \s-1IDL.\s0
|
||||
.IP "\fI\-\-dump\-idl\fR" 4
|
||||
.IX Item "--dump-idl"
|
||||
Generate a new \s-1IDL\s0 file. File will be named \s-1OUTNAME\s0.idl.
|
||||
.IP "\fI\-\-header\fR" 4
|
||||
.IX Item "--header"
|
||||
Generate a C header file for the specified interface. Filename defaults to \s-1OUTNAME\s0.h.
|
||||
.IP "\fI\-\-ndr\-parser\fR" 4
|
||||
.IX Item "--ndr-parser"
|
||||
Generate a C file and C header containing \s-1NDR\s0 parsers. The filename for
|
||||
the parser defaults to ndr_OUTNAME.c. The header filename will be the
|
||||
parser filename with the extension changed from .c to .h.
|
||||
.IP "\fI\-\-tdr\-parser\fR" 4
|
||||
.IX Item "--tdr-parser"
|
||||
Generate a C file and C header containing \s-1TDR\s0 parsers. The filename for
|
||||
the parser defaults to tdr_OUTNAME.c. The header filename will be the
|
||||
parser filename with the extension changed from .c to .h.
|
||||
.IP "\fI\-\-typelib\fR" 4
|
||||
.IX Item "--typelib"
|
||||
Write type information to the specified file.
|
||||
.IP "\fI\-\-server\fR" 4
|
||||
.IX Item "--server"
|
||||
Generate boilerplate for the \s-1RPC\s0 server that implements
|
||||
the interface. Filename defaults to ndr_OUTNAME_s.c.
|
||||
.IP "\fI\-\-template\fR" 4
|
||||
.IX Item "--template"
|
||||
Generate stubs for a \s-1RPC\s0 server that implements the interface. Output will
|
||||
be written to stdout.
|
||||
.IP "\fI\-\-ws\-parser\fR" 4
|
||||
.IX Item "--ws-parser"
|
||||
Generate an Wireshark dissector (in C) and header file. The dissector filename
|
||||
defaults to packet\-dcerpc\-OUTNAME.c while the header filename defaults to
|
||||
packet\-dcerpc\-OUTNAME.h.
|
||||
.Sp
|
||||
Pidl will read additional data from an Wireshark conformance file if present.
|
||||
Such a file should have the same location as the \s-1IDL\s0 file but with the
|
||||
extension \fIcnf\fR rather than \fIidl\fR. See Parse::Pidl::Wireshark::Conformance
|
||||
for details on the format of this file.
|
||||
.IP "\fI\-\-diff\fR" 4
|
||||
.IX Item "--diff"
|
||||
Parse an \s-1IDL\s0 file, generate a new \s-1IDL\s0 file based on the internal data
|
||||
structures and see if there are any differences with the original \s-1IDL\s0 file.
|
||||
Useful for debugging pidl.
|
||||
.IP "\fI\-\-dump\-idl\-tree\fR" 4
|
||||
.IX Item "--dump-idl-tree"
|
||||
Tell pidl to dump the internal tree representation of an \s-1IDL\s0
|
||||
file the to disk. Useful for debugging pidl.
|
||||
.IP "\fI\-\-dump\-ndr\-tree\fR" 4
|
||||
.IX Item "--dump-ndr-tree"
|
||||
Tell pidl to dump the internal \s-1NDR\s0 information tree it generated
|
||||
from the \s-1IDL\s0 file to disk. Useful for debugging pidl.
|
||||
.IP "\fI\-\-samba3\-ndr\-client\fR" 4
|
||||
.IX Item "--samba3-ndr-client"
|
||||
Generate client calls for Samba3, to be placed in rpc_client/. Instead of
|
||||
calling out to the code in Samba3's rpc_parse/, this will call out to
|
||||
Samba4's \s-1NDR\s0 code instead.
|
||||
.IP "\fI\-\-samba3\-ndr\-server\fR" 4
|
||||
.IX Item "--samba3-ndr-server"
|
||||
Generate server calls for Samba3, to be placed in rpc_server/. Instead of
|
||||
calling out to the code in Samba3's rpc_parse/, this will call out to
|
||||
Samba4's \s-1NDR\s0 code instead.
|
||||
.SH "IDL SYNTAX"
|
||||
.IX Header "IDL SYNTAX"
|
||||
\&\s-1IDL\s0 files are always preprocessed using the C preprocessor.
|
||||
.PP
|
||||
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.
|
||||
.PP
|
||||
See the section \s-1COMPATIBILITY\s0 for the list of attributes that
|
||||
pidl supports.
|
||||
.PP
|
||||
C\-style comments can be used.
|
||||
.SS "\s-1CONFORMANT ARRAYS\s0"
|
||||
.IX Subsection "CONFORMANT ARRAYS"
|
||||
A conformant array is one with that ends in [*] or []. The strange
|
||||
things about conformant arrays are that they can only appear as the last
|
||||
element of a structure (unless there is a pointer to the conformant array,
|
||||
of course) and the array size appears before the structure itself on the wire.
|
||||
.PP
|
||||
So, in this example:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& typedef struct {
|
||||
\& long abc;
|
||||
\& long count;
|
||||
\& long foo;
|
||||
\& [size_is(count)] long s[*];
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.PP
|
||||
it appears like this:
|
||||
.PP
|
||||
.Vb 1
|
||||
\& [size_is] [abc] [count] [foo] [s...]
|
||||
.Ve
|
||||
.PP
|
||||
the first [size_is] field is the allocation size of the array, and
|
||||
occurs before the array elements and even before the structure
|
||||
alignment.
|
||||
.PP
|
||||
Note that \fIsize_is()\fR can refer to a constant, but that doesn't change
|
||||
the wire representation. It does not make the array a fixed array.
|
||||
.PP
|
||||
midl.exe would write the above array as the following C header:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& typedef struct {
|
||||
\& long abc;
|
||||
\& long count;
|
||||
\& long foo;
|
||||
\& long s[1];
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.PP
|
||||
pidl takes a different approach, and writes it like this:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& typedef struct {
|
||||
\& long abc;
|
||||
\& long count;
|
||||
\& long foo;
|
||||
\& long *s;
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.SS "\s-1VARYING ARRAYS\s0"
|
||||
.IX Subsection "VARYING ARRAYS"
|
||||
A varying array looks like this:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& typedef struct {
|
||||
\& long abc;
|
||||
\& long count;
|
||||
\& long foo;
|
||||
\& [size_is(count)] long *s;
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.PP
|
||||
This will look like this on the wire:
|
||||
.PP
|
||||
.Vb 1
|
||||
\& [abc] [count] [foo] [PTR_s] [count] [s...]
|
||||
.Ve
|
||||
.SS "\s-1FIXED ARRAYS\s0"
|
||||
.IX Subsection "FIXED ARRAYS"
|
||||
A fixed array looks like this:
|
||||
.PP
|
||||
.Vb 3
|
||||
\& typedef struct {
|
||||
\& long s[10];
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.PP
|
||||
The \s-1NDR\s0 representation looks just like 10 separate long
|
||||
declarations. The array size is not encoded on the wire.
|
||||
.PP
|
||||
pidl also supports \*(L"inline\*(R" arrays, which are not part of the \s-1IDL/NDR\s0
|
||||
standard. These are declared like this:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& typedef struct {
|
||||
\& uint32 foo;
|
||||
\& uint32 count;
|
||||
\& uint32 bar;
|
||||
\& long s[count];
|
||||
\& } Struct1;
|
||||
.Ve
|
||||
.PP
|
||||
This appears like this:
|
||||
.PP
|
||||
.Vb 1
|
||||
\& [foo] [count] [bar] [s...]
|
||||
.Ve
|
||||
.PP
|
||||
Fixed arrays are an extension added to support some of the strange
|
||||
embedded structures in security descriptors and spoolss.
|
||||
.PP
|
||||
This section is by no means complete. See the OpenGroup and \s-1MSDN
|
||||
\&\s0 documentation for additional information.
|
||||
.SH "COMPATIBILITY WITH MIDL"
|
||||
.IX Header "COMPATIBILITY WITH MIDL"
|
||||
.SS "Missing features in pidl"
|
||||
.IX Subsection "Missing features in pidl"
|
||||
The following \s-1MIDL\s0 features are not (yet) implemented in pidl
|
||||
or are implemented with an incompatible interface:
|
||||
.IP "\(bu" 4
|
||||
Asynchronous communication
|
||||
.IP "\(bu" 4
|
||||
Typelibs (.tlb files)
|
||||
.IP "\(bu" 4
|
||||
Datagram support (ncadg_*)
|
||||
.SS "Supported attributes and statements"
|
||||
.IX Subsection "Supported attributes and statements"
|
||||
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, represent_as,
|
||||
transmit_as, import, include, cpp_quote.
|
||||
.SS "\s-1PIDL\s0 Specific properties"
|
||||
.IX Subsection "PIDL Specific properties"
|
||||
.IP "public" 4
|
||||
.IX Item "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.
|
||||
.IP "noprint" 4
|
||||
.IX Item "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.
|
||||
.IP "value" 4
|
||||
.IX Item "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 \s-1API\s0 more programmer friendly. The
|
||||
expression can be any C expression.
|
||||
.IP "relative" 4
|
||||
.IX Item "relative"
|
||||
The [relative] property can be supplied on a pointer. When it is used
|
||||
it declares the pointer as a spoolss style \*(L"relative\*(R" pointer, which
|
||||
means it appears on the wire as an offset within the current
|
||||
encapsulating structure. This is not part of normal \s-1IDL/NDR,\s0 but it is
|
||||
a very useful extension as it avoids the manual encoding of many
|
||||
complex structures.
|
||||
.IP "subcontext(length)" 4
|
||||
.IX Item "subcontext(length)"
|
||||
Specifies that a size of \fIlength\fR
|
||||
bytes should be read, followed by a blob of that size,
|
||||
which will be parsed as \s-1NDR.\s0
|
||||
.Sp
|
||||
\&\fIsubcontext()\fR is deprecated now, and should not be used in new code.
|
||||
Instead, use \fIrepresent_as()\fR or \fItransmit_as()\fR.
|
||||
.IP "flag" 4
|
||||
.IX Item "flag"
|
||||
Specify boolean options, mostly used for
|
||||
low-level \s-1NDR\s0 options. Several options
|
||||
can be specified using the | character.
|
||||
Note that flags are inherited by substructures!
|
||||
.IP "nodiscriminant" 4
|
||||
.IX Item "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 \s-1IDL/NDR,\s0 but is used for some
|
||||
spoolss structures.
|
||||
.IP "charset(name)" 4
|
||||
.IX Item "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 \s-1UCS2, DOS\s0 and \s-1UTF8.\s0
|
||||
.SS "Unsupported \s-1MIDL\s0 properties or statements"
|
||||
.IX Subsection "Unsupported MIDL properties or statements"
|
||||
aggregatable, appobject, async_uuid, bindable, control,
|
||||
defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface,
|
||||
displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext,
|
||||
helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib,
|
||||
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, uidefault,
|
||||
usesgetlasterror, vararg, vi_progid, wire_marshal.
|
||||
.SH "EXAMPLES"
|
||||
.IX Header "EXAMPLES"
|
||||
.Vb 2
|
||||
\& # Generating an Wireshark parser
|
||||
\& $ ./pidl \-\-ws\-parser \-\- atsvc.idl
|
||||
\&
|
||||
\& # Generating a TDR parser and header
|
||||
\& $ ./pidl \-\-tdr\-parser \-\-header \-\- regf.idl
|
||||
\&
|
||||
\& # Generating a Samba3 client and server
|
||||
\& $ ./pidl \-\-samba3\-ndr\-client \-\-samba3\-ndr\-server \-\- dfs.idl
|
||||
\&
|
||||
\& # Generating a Samba4 NDR parser, client and server
|
||||
\& $ ./pidl \-\-ndr\-parser \-\-ndr\-client \-\-ndr\-server \-\- samr.idl
|
||||
.Ve
|
||||
.SH "SEE ALSO"
|
||||
.IX Header "SEE ALSO"
|
||||
<https://msdn.microsoft.com/en\-us/library/windows/desktop/aa373864%28v=vs.85%29.aspx>
|
||||
<https://wiki.wireshark.org/DCE/RPC>,
|
||||
<https://www.samba.org/>,
|
||||
\&\fIyapp\fR\|(1)
|
||||
.SH "LICENSE"
|
||||
.IX Header "LICENSE"
|
||||
pidl is licensed under the \s-1GNU\s0 General Public License <https://www.gnu.org/licenses/gpl.html>.
|
||||
.SH "AUTHOR"
|
||||
.IX Header "AUTHOR"
|
||||
pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer
|
||||
Vernooij. The current maintainer is Jelmer Vernooij.
|
||||
.PP
|
||||
This manpage was written by Jelmer Vernooij, partially based on the original
|
||||
pidl \s-1README\s0 by Andrew Tridgell.
|
||||
Loading…
Add table
Add a link
Reference in a new issue