path: root/usr/src/tools/ndrgen/ndrgen.1onbld

.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
.\" Use is subject to license terms.
.\"
'\" te
.TH NDRGEN 1ONBLD "Oct 22, 2007"
.SH NAME
ndrgen \- NDL RPC protocol compiler
.SH SYNOPSIS
.LP
.nf
\fBndrgen\fR [ -Y \fIcpp-path\fR ] \fIfile\fR [ \fIfile\fR ] \&.\|.\|.
.fi

.SH DESCRIPTION
.LP
The \fBndrgen\fR utility is a tool that generates C code to implement a DCERPC/MSRPC Network Data Representation (NDR) protocol. The input to \fBndrgen\fR is a language similar to C known as Network Data Language (NDL).
.sp
.LP
The \fBndrgen\fR 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 \fBproto.ndl\fR, \fBndrgen\fR generates NDR routines in \fBproto_ndr.c\fR. Applications must define the service definition and server-side stub table for use with the RPC protocol.
.sp
.LP
The following is an example stub table and service definition:
.sp
.in +2
.nf
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 */
};
.fi
.in -2

.sp
.LP
The C preprocessor, which can be specified in the \fBCC\fR environment variable or on the command line, is run on the input file before it is interpreted by \fBndrgen\fR. The \fBNDRGEN\fR preprocessor symbol is defined by \fBndrgen\fR for use by the \fBndrgen\fR programmer.
.sp
.LP
The NDR generated by \fBndrgen\fR 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.
.sp
.LP
The following table shows the DCE RPC layering compared against ONC RPC.
.sp
.in +2
.nf
 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      |
+---------------+       +---------------+
.fi
.in -2

.sp
.LP
There are two major differences between the DCE RPC and ONC RPC:
.RS +4
.TP
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.
.sp
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.
.RE
.RS +4
.TP
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.
.sp
ONC RPC uses \fBmalloc()\fR liberally throughout its run-time system. To free results, ONC RPC supports an \fBXDR_FREE\fR operation that traverses data structures freeing memory as it goes.
.RE
.sp
.LP
The following terminology is used in the subsequent discussion of NDR.
.sp
.ne 2
.na
\fBSize\fR
.ad
.sp .6
.RS 4n
The size of an array in elements, such as the amount to \fBmalloc()\fR.
.RE

.sp
.ne 2
.na
\fBLength\fR
.ad
.sp .6
.RS 4n
The number of significant elements of an array.
.RE

.sp
.ne 2
.na
\fBKnown\fR
.ad
.sp .6
.RS 4n
Size or Length is known at build time.
.RE

.sp
.ne 2
.na
\fBDetermined\fR
.ad
.sp .6
.RS 4n
Size or Length is determined at run time.
.RE

.sp
.ne 2
.na
\fBFixed\fR
.ad
.sp .6
.RS 4n
The Size and Length are Known, such as a string constant:
.sp
.in +2
.nf
char array[] = "A constant Size/Length";
.fi
.in -2

.RE

.sp
.LP
The following DCE RPC terminology is used in the subsequent discussion.
.sp
.ne 2
.na
\fBConformant\fR
.ad
.sp .6
.RS 4n
The Size is Determined. The Length is the same as Size.
.sp

.RE
.sp
.ne 2

.na
\fBVarying\fR
.ad
.sp .6
.RS 4n
The Size is Known. The Length is Determined, such as a \fBstrcpy()\fR of a variable length string into a fixed length buffer:
.sp
.in +2
.nf
char array[100];
strcpy(array, "very short string");
.fi
.in -2

.RE

.sp
.ne 2
.na
\fBVarying and Conformant\fR
.ad
.sp .6
.RS 4n
The Size is Determined. The Length is separately Determined, such as:
.sp
.in +2
.nf
char *array = malloc(size);
strcpy(array, "short string");
.fi
.in -2

.RE

.SS "Strings"
.LP
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.
.sp
.LP
MSRPC strings are always varying and conformant format and not null terminated. This format uses the \fIsize_is\fR, \fIfirst_is\fR, and \fIlength_is\fR attributes:
.sp
.in +2
.nf
typedef struct string {
   DWORD size_is;
   DWORD first_is;
   DWORD length_is;
   wchar_t string[ANY_SIZE_ARRAY];
} string_t;
.fi
.in -2

.sp
.LP
The \fIsize_is\fR attribute is used to specify the number of data elements in each dimension of an array.
.sp
.LP
The \fIfirst_is\fR attribute is used to define the lower bound for significant elements in each dimension of an array. For strings, this value is always zero.
.sp
.LP
The \fIlength_is\fR 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 \fIsize_is\fR, although it might be (\fIsize_is\fR - 1) if the string is null terminated.
.sp
.LP
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.
.sp
.in +2
.nf
 4 bytes   4 bytes   4 bytes   2bytes 2bytes 2bytes 2bytes
+---------+---------+---------+------+------+------+------+
|size_is  |first_is |length_is| char | char | char | char |
+---------+---------+---------+------+------+------+------+
.fi
.in -2

.sp
.LP
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 \fBstring_t\fR by the NDR library.
.sp
.in +2
.nf
typedef struct msrpc_string {
   WORD length;
   WORD maxlen;
   LPTSTR str;
} msrpc_string_t;
.fi
.in -2

.sp
.LP
Here, \fIlength\fR is the array length in bytes excluding any terminating null bytes and \fImaxlen\fR is the array length in bytes including the terminating null bytes.
.SS "NDL Syntax"
.LP
The \fBndrgen\fR 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:
.sp
.in +2
.nf
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]
.fi
.in -2

.sp
.LP
The following shows the C data type associated with the NDRGEN NDL:
.sp
.in +2
.nf
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 *
.fi
.in -2

.SH OPTIONS
.LP
The \fBsmbutil\fR command supports the following global option:
.sp
.ne 2
.na
\fB\fB-Y\fR\fR
.ad
.RS 13n
Specifies the path to the \fBcpp\fR program.
.RE

.SH EXAMPLES
.LP
The following is an example NDL header file:
.sp
.in +2
.nf
#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_ */
.fi
.in -2

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB0\fR
.ad
.RS 13n
Successful operation.
.RE

.sp
.ne 2
.na
\fB>0\fR
.ad
.RS 13n
An error occurred.
.RE

.SH ATTRIBUTES
See the \fBattributes\fR(5) man page for descriptions of the following attributes:
.sp

.sp
.TS
box;
cw | cw
lw | lw .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Availability	SUNWbtool
.TE

.SH SEE ALSO
.LP
\fBcpp\fR(1), \fBrpcgen\fR(1), \fBcc\fR(1B), \fBattributes\fR(5)
.SH BUGS
.LP
Some \fBcpp\fR(1) macros used by \fBndrgen\fR are not understood by \fB/usr/bin/cpp\fR or \fB/usr/sfw/bin/cpp\fR. Simple NDL files generally do not pose a problem. If problems occur, for example, when using unions, use \fB/usr/libexec/cpp\fR or \fBcw\fR.