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 = {
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.
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]
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 /*
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.
|
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
33
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 };
53
54 static service_t net_svc = {
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
141
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
151
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
161
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
171
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
186
187 .RE
188
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
201
202 .RE
203 .sp
204 .ne 2
205
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
219
220 .RE
221
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
237
238 .RE
239
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
257
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.
278 .in -2
279
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
293
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]
322
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
340
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
352
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_
361
362 #include "ndrtypes.ndl"
363
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
372
373 /*
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)
443
444 #endif /* _SVC_NDL_ */
445 .fi
446 .in -2
447
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
459
460 .sp
461 .ne 2
462 .na
463 \fB>0\fR
464 .ad
465 .RS 13n
466 An error occurred.
467 .RE
468
469 .SH ATTRIBUTES
470 See the \fBattributes\fR(5) man page for descriptions of the following attributes:
471 .sp
472
473 .sp
474 .TS
475 box;
476 cw | cw
477 lw | lw .
478 ATTRIBUTE TYPE ATTRIBUTE VALUE
479 _
480 Availability SUNWbtool
481 .TE
482
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.
|