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