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