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