424 lines
16 KiB
Groff
424 lines
16 KiB
Groff
.\" 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.
|