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