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

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 */
 "\e\enetsvc", /* endpoint */
 "\e\epipe\e\enetsvc", /* 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.

 DCE RPC Layers ONC RPC Layers Remark
+---------------+ +---------------+ +----------------+
+---------------+ +---------------+
| Application | | Application | The application
+---------------+ +---------------+
| Hand coded | | RPCGEN gen'd |
| client/server | | client/server | Generated stubs
| proto.ndl | | *_svc.c *_clnt|
| proto.c | | |
+---------------+ +---------------+
| | | | Binding/PMAP
| RPC Library | | RPC Library | Calls/Return
+---------------+ +---------------+
| RPC Protocol | | RPC Protocol | Headers
| rpcpdu.ndl | | | Authentication
+---------------+ +---------------+
| NDRGEN gen'd | | RPCGEN gen'd | Aggregation
| NDR stubs | | XDR stubs | Composition
| *__ndr.c | | *_xdr.c |
+---------------+ +---------------+
| NDR | | XDR | Byte order, padding
+---------------+ +---------------+
| | | Network Conn | Large difference:
| Heap | | clnt_tcp | see below.
| Management | | clnt_udp |
+---------------+ +---------------+

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

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

Size

Length

Known

Determined

Fixed

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

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

Conformant

Varying

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

Varying and Conformant

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

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.

 4 bytes 4 bytes 4 bytes 2bytes 2bytes 2bytes 2bytes
+---------+---------+---------+------+------+------+------+
|size_is |first_is |length_is| char | char | char | char |
+---------+---------+---------+------+------+------+------+

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.

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 *

The smbutil command supports the following global option:

-Y

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_ */

The following exit values are returned:

0

>0

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

cpp(1), rpcgen(1), cc(1B), attributes(5)

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.