| blob | 7989b4559c7ff6cb1f0e670848d188a7b4152a2c |
1 .\"
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright 2007 Sun Microsystems, Inc. All rights reserved.
22 .\" Use is subject to license terms.
23 .\"
24 '\" te
25 .TH NDRGEN 1ONBLD "Oct 22, 2007"
26 .SH NAME
27 ndrgen \- NDL RPC protocol compiler
28 .SH SYNOPSIS
29 .LP
30 .nf
31 \fBndrgen\fR [ -Y \fIcpp-path\fR ] \fIfile\fR [ \fIfile\fR ] \&.\|.\|.
32 .fi
34 .SH DESCRIPTION
35 .LP
36 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).
37 .sp
38 .LP
39 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.
40 .sp
41 .LP
42 The following is an example stub table and service definition:
43 .sp
44 .in +2
45 .nf
46 static stub_table_t net_svc_stub_table[] = {
47 { svc_close, SVC_CLOSE },
48 { svc_open, SVC_OPEN },
49 { svc_read, SVC_READ },
50 { svc_write, SVC_WRITE },
51 {0}
52 };
54 static service_t net_svc = {
55 "NETSVC", /* name */
56 "Network Service", /* description */
57 "\e\enetsvc", /* endpoint */
58 "\e\epipe\e\enetsvc", /* secondary address port */
59 "12345678-1234-abcd-ef0001234567abcd", 1, /* abstract syntax */
60 "8a885d04-1ceb-11c9-9fe808002b104860", 2, /* transfer syntax */
61 0, /* bind_instance_size */
62 0, /* bind_req() */
63 0, /* unbind_and_close() */
64 0, /* call_stub() */
65 &TYPEINFO(svc_interface), /* interface ti */
66 net_svc_stub_table /* stub_table */
67 };
68 .fi
69 .in -2
71 .sp
72 .LP
73 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.
74 .sp
75 .LP
76 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.
77 .sp
78 .LP
79 The following table shows the DCE RPC layering compared against ONC RPC.
80 .sp
81 .in +2
82 .nf
83 DCE RPC Layers ONC RPC Layers Remark
84 +---------------+ +---------------+ +----------------+
85 +---------------+ +---------------+
86 | Application | | Application | The application
87 +---------------+ +---------------+
88 | Hand coded | | RPCGEN gen'd |
89 | client/server | | client/server | Generated stubs
90 | proto.ndl | | *_svc.c *_clnt|
91 | proto.c | | |
92 +---------------+ +---------------+
93 | | | | Binding/PMAP
94 | RPC Library | | RPC Library | Calls/Return
95 +---------------+ +---------------+
96 | RPC Protocol | | RPC Protocol | Headers
97 | rpcpdu.ndl | | | Authentication
98 +---------------+ +---------------+
99 | NDRGEN gen'd | | RPCGEN gen'd | Aggregation
100 | NDR stubs | | XDR stubs | Composition
101 | *__ndr.c | | *_xdr.c |
102 +---------------+ +---------------+
103 | NDR | | XDR | Byte order, padding
104 +---------------+ +---------------+
105 | | | Network Conn | Large difference:
106 | Heap | | clnt_tcp | see below.
107 | Management | | clnt_udp |
108 +---------------+ +---------------+
109 .fi
110 .in -2
112 .sp
113 .LP
114 There are two major differences between the DCE RPC and ONC RPC:
115 .RS +4
116 .TP
117 1.
118 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.
119 .sp
120 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.
121 .RE
122 .RS +4
123 .TP
124 2.
125 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.
126 .sp
127 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.
128 .RE
129 .sp
130 .LP
131 The following terminology is used in the subsequent discussion of NDR.
132 .sp
133 .ne 2
134 .na
135 \fBSize\fR
136 .ad
137 .sp .6
138 .RS 4n
139 The size of an array in elements, such as the amount to \fBmalloc()\fR.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fBLength\fR
146 .ad
147 .sp .6
148 .RS 4n
149 The number of significant elements of an array.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fBKnown\fR
156 .ad
157 .sp .6
158 .RS 4n
159 Size or Length is known at build time.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fBDetermined\fR
166 .ad
167 .sp .6
168 .RS 4n
169 Size or Length is determined at run time.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fBFixed\fR
176 .ad
177 .sp .6
178 .RS 4n
179 The Size and Length are Known, such as a string constant:
180 .sp
181 .in +2
182 .nf
183 char array[] = "A constant Size/Length";
184 .fi
185 .in -2
187 .RE
189 .sp
190 .LP
191 The following DCE RPC terminology is used in the subsequent discussion.
192 .sp
193 .ne 2
194 .na
195 \fBConformant\fR
196 .ad
197 .sp .6
198 .RS 4n
199 The Size is Determined. The Length is the same as Size.
200 .sp
202 .RE
203 .sp
204 .ne 2
206 .na
207 \fBVarying\fR
208 .ad
209 .sp .6
210 .RS 4n
211 The Size is Known. The Length is Determined, such as a \fBstrcpy()\fR of a variable length string into a fixed length buffer:
212 .sp
213 .in +2
214 .nf
215 char array[100];
216 strcpy(array, "very short string");
217 .fi
218 .in -2
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fBVarying and Conformant\fR
226 .ad
227 .sp .6
228 .RS 4n
229 The Size is Determined. The Length is separately Determined, such as:
230 .sp
231 .in +2
232 .nf
233 char *array = malloc(size);
234 strcpy(array, "short string");
235 .fi
236 .in -2
238 .RE
240 .SS "Strings"
241 .LP
242 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.
243 .sp
244 .LP
245 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:
246 .sp
247 .in +2
248 .nf
249 typedef struct string {
250 DWORD size_is;
251 DWORD first_is;
252 DWORD length_is;
253 wchar_t string[ANY_SIZE_ARRAY];
254 } string_t;
255 .fi
256 .in -2
258 .sp
259 .LP
260 The \fIsize_is\fR attribute is used to specify the number of data elements in each dimension of an array.
261 .sp
262 .LP
263 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.
264 .sp
265 .LP
266 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.
267 .sp
268 .LP
269 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.
270 .sp
271 .in +2
272 .nf
273 4 bytes 4 bytes 4 bytes 2bytes 2bytes 2bytes 2bytes
274 +---------+---------+---------+------+------+------+------+
275 |size_is |first_is |length_is| char | char | char | char |
276 +---------+---------+---------+------+------+------+------+
277 .fi
278 .in -2
280 .sp
281 .LP
282 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.
283 .sp
284 .in +2
285 .nf
286 typedef struct msrpc_string {
287 WORD length;
288 WORD maxlen;
289 LPTSTR str;
290 } msrpc_string_t;
291 .fi
292 .in -2
294 .sp
295 .LP
296 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.
297 .SS "NDL Syntax"
298 .LP
299 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:
300 .sp
301 .in +2
302 .nf
303 NDRGEN NDL DCE RPC IDL
304 ================================
305 OPERATION(X) [operation(X)]
306 IN [in]
307 OUT [out]
308 INOUT [in out]
309 STRING [string]
310 SIZE_IS(X) [size_is(X)]
311 SWITCH(X) [switch_is(X)]
312 CASE(X) [case(X)]
313 DEFAULT [default]
314 INTERFACE(X) [interface(X)]
315 UUID(X) [uuid(X)]
316 ARG_IS(X) [arg_is(X)]
317 REFERENCE [reference]
318 ANY_SIZE_ARRAY *
319 IMPORT_EXTERN [extern]
320 .fi
321 .in -2
323 .sp
324 .LP
325 The following shows the C data type associated with the NDRGEN NDL:
326 .sp
327 .in +2
328 .nf
329 NDRGEN NDL C Data Type
330 ==============================
331 BYTE unsigned char
332 WORD unsigned short
333 DWORD unsigned long
334 LPTSTR wchar_t *
335 LPBYTE unsigned char *
336 LPWORD unsigned short *
337 LPDWORD unsigned long *
338 .fi
339 .in -2
341 .SH OPTIONS
342 .LP
343 The \fBsmbutil\fR command supports the following global option:
344 .sp
345 .ne 2
346 .na
347 \fB\fB-Y\fR\fR
348 .ad
349 .RS 13n
350 Specifies the path to the \fBcpp\fR program.
351 .RE
353 .SH EXAMPLES
354 .LP
355 The following is an example NDL header file:
356 .sp
357 .in +2
358 .nf
359 #ifndef _SVC_NDL_
360 #define _SVC_NDL_
362 #include "ndrtypes.ndl"
364 /*
365 * Opnums: note that ndrgen does not automatically number
366 * operations and the values do not have to be sequential.
367 */
368 #define SVC_CLOSE 0x00
369 #define SVC_OPEN 0x01
370 #define SVC_READ 0x02
371 #define SVC_WRITE 0x03
373 /*
374 * Define a file handle - choice of UUID format is
375 * arbitrary. Note that typedef's cannot be declared
376 * with the struct definition.
377 */
378 struct svc_uuid {
379 DWORD data1;
380 DWORD data2;
381 WORD data3[2];
382 BYTE data4[8];
383 };
384 typedef struct svc_uuid svc_handle_t;
386 struct xferbuf {
387 DWORD nbytes;
388 DWORD offset;
389 SIZE_IS(nbytes) BYTE *data;
390 };
391 typedef struct xferbuf xferbuf_t;
393 /*
394 * Define the RPC operations.
395 */
396 OPERATION(SVC_CLOSE)
397 struct svc_close {
398 IN svc_handle_t handle;
399 OUT DWORD status;
400 };
402 OPERATION(SVC_OPEN)
403 struct svc_open {
404 IN LPTSTR servername;
405 IN LPTSTR path;
406 OUT svc_handle_t handle;
407 OUT DWORD status;
408 };
410 OPERATION(SVC_READ)
411 struct svc_read {
412 IN svc_handle_t handle;
413 IN DWORD nbytes;
414 IN DWORD offset;
415 OUT xferbuf_t buf;
416 OUT DWORD status;
417 };
419 OPERATION(SVC_WRITE)
420 struct svc_write {
421 IN svc_handle_t handle;
422 IN xferbuf_t buf;
423 OUT DWORD nbytes;
424 OUT DWORD status;
425 };
427 /*
428 * Define the interface.
429 */
430 INTERFACE(0)
431 union svc_interface {
432 CASE(SVC_CLOSE)
433 struct svc_close net_close;
434 CASE(SVC_OPEN)
435 struct svc_open net_open;
436 CASE(SVC_READ)
437 struct svc_read net_read;
438 CASE(SVC_WRITE)
439 struct svc_write net_write;
440 };
441 typedef union svc_interface svc_interface_t;
442 EXTERNTYPEINFO(svc_interface)
444 #endif /* _SVC_NDL_ */
445 .fi
446 .in -2
448 .SH EXIT STATUS
449 .LP
450 The following exit values are returned:
451 .sp
452 .ne 2
453 .na
454 \fB0\fR
455 .ad
456 .RS 13n
457 Successful operation.
458 .RE
460 .sp
461 .ne 2
462 .na
463 \fB>0\fR
464 .ad
465 .RS 13n
466 An error occurred.
467 .RE
469 .SH ATTRIBUTES
470 See the \fBattributes\fR(5) man page for descriptions of the following attributes:
471 .sp
473 .sp
474 .TS
475 box;
476 cw | cw
477 lw | lw .
478 ATTRIBUTE TYPE ATTRIBUTE VALUE
479 _
480 Availability SUNWbtool
481 .TE
483 .SH SEE ALSO
484 .LP
485 \fBcpp\fR(1), \fBrpcgen\fR(1), \fBcc\fR(1B), \fBattributes\fR(5)
486 .SH BUGS
487 .LP
488 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.