NAME

ndrgen - NDL RPC protocol compiler

SYNOPSIS

ndrgen [ -Y cpp-path ] file [ file ] ...

DESCRIPTION

The ndrgen utility is a tool that generates C code to implement a DCERPC/MSRPC Network Data Representation (NDR) protocol. The input to ndrgen is a language similar to C known as Network Data Language (NDL).

The ndrgen utility takes an input protocol definition file and generates an output C source file that contains the marshalling routines to implement the RPC protocol. If the input file is named proto.ndl, ndrgen generates NDR routines in proto_ndr.c. Applications must define the service definition and server-side stub table for use with the RPC protocol.

The following is an example stub table and service definition:

static stub_table_t net_svc_stub_table[] = {
{ svc_close, SVC_CLOSE },
{ svc_open, SVC_OPEN },
{ svc_read, SVC_READ },
{ svc_write, SVC_WRITE },
{0}
};

static service_t net_svc = {
"NETSVC", /* name */
"Network Service", /* description */
"\\netsvc", /* endpoint */
"\\pipe\\netsvc", /* secondary address port */
"12345678-1234-abcd-ef0001234567abcd", 1, /* abstract syntax */
"8a885d04-1ceb-11c9-9fe808002b104860", 2, /* transfer syntax */
0, /* bind_instance_size */
0, /* bind_req() */
0, /* unbind_and_close() */
0, /* call_stub() */
&TYPEINFO(svc_interface), /* interface ti */
net_svc_stub_table /* stub_table */
};

The C preprocessor, which can be specified in the CC environment variable or on the command line, is run on the input file before it is interpreted by ndrgen. The NDRGEN preprocessor symbol is defined by ndrgen for use by the ndrgen programmer.

The NDR generated by ndrgen is an MSRPC compatible implementation of OSF DCE NDR. This implementation is based on the X/Open DCE: Remote Procedure Call specification (CAE Specification (1997), DCE 1.1: Remote Procedure Call Document Number: C706), enhanced for compatibility with MSRPC Unicode (UCS-2) strings.

The following table shows the DCE RPC layering compared against ONC RPC.

There are two major differences between the DCE RPC and ONC RPC:

1.: DCE RPC only generates or processes packets from buffers. Other layers must take care of packet transmission and reception. The packet heaps are managed through a simple interface provided by NDR streams.

ONC RPC communicates directly with the network. The programmer must do specific setup for the RPC packet to be placed in a buffer rather than sent to the wire.

2.: DCE RPC uses application provided heaps to support operations. A heap is a managed chunk of memory that NDR manages as it allocates. When the operation and its result are complete, the heap is disposed of as a single item. Transactions, which are the anchor of most operations, perform heap bookkeeping.

ONC RPC uses malloc() liberally throughout its run-time system. To free results, ONC RPC supports an XDR_FREE operation that traverses data structures freeing memory as it goes.

The following terminology is used in the subsequent discussion of NDR.

Size

The size of an array in elements, such as the amount to malloc().

Length

The number of significant elements of an array.

Known

Size or Length is known at build time.

Determined

Size or Length is determined at run time.

Fixed

The Size and Length are Known, such as a string constant:

char array[] = "A constant Size/Length";

The following DCE RPC terminology is used in the subsequent discussion.

Conformant

The Size is Determined. The Length is the same as Size.

Varying

The Size is Known. The Length is Determined, such as a strcpy() of a variable length string into a fixed length buffer:

char array[100];
strcpy(array, "very short string");

Varying and Conformant

The Size is Determined. The Length is separately Determined, such as:

char *array = malloc(size);
strcpy(array, "short string");

Strings

DCE RPC strings are represented as varying or varying and conformant one-dimensional arrays. Characters can be single-byte or multi-byte as long as all characters conform to a fixed element size. For instance, UCS-2 is valid, but UTF-8 is not a valid DCE RPC string format. The string is terminated by a null character of the appropriate element size.

MSRPC strings are always varying and conformant format and not null terminated. This format uses the size_is, first_is, and length_is attributes:

typedef struct string {
DWORD size_is;
DWORD first_is;
DWORD length_is;
wchar_t string[ANY_SIZE_ARRAY];
} string_t;

The size_is attribute is used to specify the number of data elements in each dimension of an array.

The first_is attribute is used to define the lower bound for significant elements in each dimension of an array. For strings, this value is always zero.

The length_is attribute is used to define the number of significant elements in each dimension of an array. For strings, this value is typically the same as size_is, although it might be (size_is - 1) if the string is null terminated.

MSRPC Unicode strings are not null terminated, which means that the recipient must manually null-terminate the string after it has been received. Note that there is often a wide-char pad following a string, which might contain zero but this situation is not guaranteed.

Despite the general rule, some MSRPC services use null-terminated Unicode strings. To compensate, MSRPC uses the following additional string wrapper with two additional fields. Note that LPTSTR is automatically converted to string_t by the NDR library.

typedef struct msrpc_string {
WORD length;
WORD maxlen;
LPTSTR str;
} msrpc_string_t;

Here, length is the array length in bytes excluding any terminating null bytes and maxlen is the array length in bytes including the terminating null bytes.

NDL Syntax

The ndrgen input must be a valid C header file. Thus, NDL is defined by using macros to map to DCE RPC IDL. The following shows the mappings:

NDRGEN NDL DCE RPC IDL
================================
OPERATION(X) [operation(X)]
IN [in]
OUT [out]
INOUT [in out]
STRING [string]
SIZE_IS(X) [size_is(X)]
SWITCH(X) [switch_is(X)]
CASE(X) [case(X)]
DEFAULT [default]
INTERFACE(X) [interface(X)]
UUID(X) [uuid(X)]
ARG_IS(X) [arg_is(X)]
REFERENCE [reference]
ANY_SIZE_ARRAY *
IMPORT_EXTERN [extern]

The following shows the C data type associated with the NDRGEN NDL:

NDRGEN NDL C Data Type
==============================
BYTE unsigned char
WORD unsigned short
DWORD unsigned long
LPTSTR wchar_t *
LPBYTE unsigned char *
LPWORD unsigned short *
LPDWORD unsigned long *

OPTIONS

The smbutil command supports the following global option:

-Y

Specifies the path to the cpp program.

EXAMPLES

The following is an example NDL header file:

#ifndef _SVC_NDL_
#define _SVC_NDL_

#include "ndrtypes.ndl"

/*
* Opnums: note that ndrgen does not automatically number
* operations and the values do not have to be sequential.
*/
#define SVC_CLOSE 0x00
#define SVC_OPEN 0x01
#define SVC_READ 0x02
#define SVC_WRITE 0x03

/*
* Define a file handle - choice of UUID format is
* arbitrary. Note that typedef's cannot be declared
* with the struct definition.
*/
struct svc_uuid {
DWORD data1;
DWORD data2;
WORD data3[2];
BYTE data4[8];
};
typedef struct svc_uuid svc_handle_t;

struct xferbuf {
DWORD nbytes;
DWORD offset;
SIZE_IS(nbytes) BYTE *data;
};
typedef struct xferbuf xferbuf_t;

/*
* Define the RPC operations.
*/
OPERATION(SVC_CLOSE)
struct svc_close {
IN svc_handle_t handle;
OUT DWORD status;
};

OPERATION(SVC_OPEN)
struct svc_open {
IN LPTSTR servername;
IN LPTSTR path;
OUT svc_handle_t handle;
OUT DWORD status;
};

OPERATION(SVC_READ)
struct svc_read {
IN svc_handle_t handle;
IN DWORD nbytes;
IN DWORD offset;
OUT xferbuf_t buf;
OUT DWORD status;
};

OPERATION(SVC_WRITE)
struct svc_write {
IN svc_handle_t handle;
IN xferbuf_t buf;
OUT DWORD nbytes;
OUT DWORD status;
};

/*
* Define the interface.
*/
INTERFACE(0)
union svc_interface {
CASE(SVC_CLOSE)
struct svc_close net_close;
CASE(SVC_OPEN)
struct svc_open net_open;
CASE(SVC_READ)
struct svc_read net_read;
CASE(SVC_WRITE)
struct svc_write net_write;
};
typedef union svc_interface svc_interface_t;
EXTERNTYPEINFO(svc_interface)

#endif /* _SVC_NDL_ */

EXIT STATUS

The following exit values are returned:

0

Successful operation.

>0

An error occurred.

ATTRIBUTES

See the attributes(5) man page for descriptions of the following attributes:

BUGS

Some cpp(1) macros used by ndrgen are not understood by /usr/bin/cpp or /usr/sfw/bin/cpp. Simple NDL files generally do not pose a problem. If problems occur, for example, when using unions, use /usr/libexec/cpp or cw.