docs/Samba-Developers-Guide/internals.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="internals">
   4 <chapterinfo>
   5         <author>
   6                 <firstname>David</firstname><surname>Chappell</surname>
   7                 <affiliation>
   8                         <address><email>David.Chappell@mail.trincoll.edu</email></address>
   9                 </affiliation>
  10         </author>
  11         <pubdate>8 May 1996</pubdate>
  12 </chapterinfo>
  13
  14 <title>Samba Internals</title>
  15
  16 <sect1>
  17 <title>Character Handling</title>
  18 <para>
  19 This section describes character set handling in Samba, as implemented in
  20 Samba 3.0 and above
  21 </para>
  22
  23 <para>
  24 In the past Samba had very ad-hoc character set handling. Scattered
  25 throughout the code were numerous calls which converted particular
  26 strings to/from DOS codepages. The problem is that there was no way of
  27 telling if a particular char* is in dos codepage or unix
  28 codepage. This led to a nightmare of code that tried to cope with
  29 particular cases without handlingt the general case.
  30 </para>
  31 </sect1>
  32
  33 <sect1>
  34 <title>The new functions</title>
  35
  36 <para>
  37 The new system works like this:
  38 </para>
  39
  40 <orderedlist>
  41 <listitem><para>
  42         all char* strings inside Samba are "unix" strings. These are
  43         multi-byte strings that are in the charset defined by the "unix
  44         charset" option in smb.conf.
  45 </para></listitem>
  46
  47 <listitem><para>
  48         there is no single fixed character set for unix strings, but any
  49         character set that is used does need the following properties:
  50         </para>
  51         <orderedlist>
  52
  53         <listitem><para>
  54                 must not contain NULLs except for termination
  55         </para></listitem>
  56
  57         <listitem><para>
  58                 must be 7-bit compatible with C strings, so that a constant
  59                 string or character in C will be byte-for-byte identical to the
  60                 equivalent string in the chosen character set.
  61         </para></listitem>
  62
  63         <listitem><para>
  64                 when you uppercase or lowercase a string it does not become
  65                 longer than the original string
  66         </para></listitem>
  67
  68         <listitem><para>
  69                 must be able to correctly hold all characters that your client
  70                 will throw at it
  71         </para></listitem>
  72         </orderedlist>
  73
  74         <para>
  75         For example, UTF-8 is fine, and most multi-byte asian character sets
  76         are fine, but UCS2 could not be used for unix strings as they
  77         contain nulls.
  78         </para>
  79 </listitem>
  80
  81 <listitem><para>
  82         when you need to put a string into a buffer that will be sent on the
  83         wire, or you need a string in a character set format that is
  84         compatible with the clients character set then you need to use a
  85         pull_ or push_ function. The pull_ functions pull a string from a
  86         wire buffer into a (multi-byte) unix string. The push_ functions
  87         push a string out to a wire buffer.
  88 </para></listitem>
  89
  90 <listitem><para>
  91         the two main pull_ and push_ functions you need to understand are
  92         pull_string and push_string. These functions take a base pointer
  93         that should point at the start of the SMB packet that the string is
  94         in. The functions will check the flags field in this packet to
  95         automatically determine if the packet is marked as a unicode packet,
  96         and they will choose whether to use unicode for this string based on
  97         that flag. You may also force this decision using the STR_UNICODE or
  98         STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper
  99         functions clistr_ and srvstr_ that call the pull_/push_ functions
 100         with the appropriate first argument.
 101         </para>
 102
 103         <para>
 104         You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2
 105         functions if you know that a particular string is ascii or
 106         unicode. There are also a number of other convenience functions in
 107         charcnv.c that call the pull_/push_ functions with particularly
 108         common arguments, such as pull_ascii_pstring()
 109         </para>
 110 </listitem>
 111
 112 <listitem><para>
 113         The biggest thing to remember is that internal (unix) strings in Samba
 114         may now contain multi-byte characters. This means you cannot assume
 115         that characters are always 1 byte long. Often this means that you will
 116         have to convert strings to ucs2 and back again in order to do some
 117         (seemingly) simple task. For examples of how to do this see functions
 118         like strchr_m(). I know this is very slow, and we will eventually
 119         speed it up but right now we want this stuff correct not fast.
 120 </para></listitem>
 121
 122 <listitem><para>
 123         all lp_ functions now return unix strings. The magic "DOS" flag on
 124         parameters is gone.
 125 </para></listitem>
 126
 127 <listitem><para>
 128         all vfs functions take unix strings. Don't convert when passing to them
 129 </para></listitem>
 130
 131 </orderedlist>
 132
 133 </sect1>
 134
 135 <sect1>
 136 <title>Macros in byteorder.h</title>
 137
 138 <para>
 139 This section describes the macros defined in byteorder.h.  These macros
 140 are used extensively in the Samba code.
 141 </para>
 142
 143 <sect2>
 144 <title>CVAL(buf,pos)</title>
 145
 146 <para>
 147 returns the byte at offset pos within buffer buf as an unsigned character.
 148 </para>
 149 </sect2>
 150
 151 <sect2>
 152 <title>PVAL(buf,pos)</title>
 153 <para>returns the value of CVAL(buf,pos) cast to type unsigned integer.</para>
 154 </sect2>
 155
 156 <sect2>
 157 <title>SCVAL(buf,pos,val)</title>
 158 <para>sets the byte at offset pos within buffer buf to value val.</para>
 159 </sect2>
 160
 161 <sect2>
 162 <title>SVAL(buf,pos)</title>
 163 <para>
 164         returns the value of the unsigned short (16 bit) little-endian integer at
 165         offset pos within buffer buf.  An integer of this type is sometimes
 166         refered to as "USHORT".
 167 </para>
 168 </sect2>
 169
 170 <sect2>
 171 <title>IVAL(buf,pos)</title>
 172 <para>returns the value of the unsigned 32 bit little-endian integer at offset
 173 pos within buffer buf.</para>
 174 </sect2>
 175
 176 <sect2>
 177 <title>SVALS(buf,pos)</title>
 178 <para>returns the value of the signed short (16 bit) little-endian integer at
 179 offset pos within buffer buf.</para>
 180 </sect2>
 181
 182 <sect2>
 183 <title>IVALS(buf,pos)</title>
 184 <para>returns the value of the signed 32 bit little-endian integer at offset pos
 185 within buffer buf.</para>
 186 </sect2>
 187
 188 <sect2>
 189 <title>SSVAL(buf,pos,val)</title>
 190 <para>sets the unsigned short (16 bit) little-endian integer at offset pos within
 191 buffer buf to value val.</para>
 192 </sect2>
 193
 194 <sect2>
 195 <title>SIVAL(buf,pos,val)</title>
 196 <para>sets the unsigned 32 bit little-endian integer at offset pos within buffer
 197 buf to the value val.</para>
 198 </sect2>
 199
 200 <sect2>
 201 <title>SSVALS(buf,pos,val)</title>
 202 <para>sets the short (16 bit) signed little-endian integer at offset pos within
 203 buffer buf to the value val.</para>
 204 </sect2>
 205
 206 <sect2>
 207 <title>SIVALS(buf,pos,val)</title>
 208 <para>sets the signed 32 bit little-endian integer at offset pos withing buffer
 209 buf to the value val.</para>
 210 </sect2>
 211
 212 <sect2>
 213 <title>RSVAL(buf,pos)</title>
 214 <para>returns the value of the unsigned short (16 bit) big-endian integer at
 215 offset pos within buffer buf.</para>
 216 </sect2>
 217
 218 <sect2>
 219 <title>RIVAL(buf,pos)</title>
 220 <para>returns the value of the unsigned 32 bit big-endian integer at offset
 221 pos within buffer buf.</para>
 222 </sect2>
 223
 224 <sect2>
 225 <title>RSSVAL(buf,pos,val)</title>
 226 <para>sets the value of the unsigned short (16 bit) big-endian integer at
 227 offset pos within buffer buf to value val.
 228 refered to as "USHORT".</para>
 229 </sect2>
 230
 231 <sect2>
 232 <title>RSIVAL(buf,pos,val)</title>
 233 <para>sets the value of the unsigned 32 bit big-endian integer at offset
 234 pos within buffer buf to value val.</para>
 235 </sect2>
 236
 237 </sect1>
 238
 239
 240 <sect1>
 241 <title>LAN Manager Samba API</title>
 242
 243 <para>
 244 This section describes the functions need to make a LAN Manager RPC call.
 245 This information had been obtained by examining the Samba code and the LAN
 246 Manager 2.0 API documentation.  It should not be considered entirely
 247 reliable.
 248 </para>
 249
 250 <para>
 251 <programlisting>
 252 call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt,
 253         char *param, char *data, char **rparam, char **rdata);
 254 </programlisting>
 255 </para>
 256
 257 <para>
 258 This function is defined in client.c.  It uses an SMB transaction to call a
 259 remote api.
 260 </para>
 261
 262 <sect2>
 263 <title>Parameters</title>
 264
 265 <para>The parameters are as follows:</para>
 266
 267 <orderedlist>
 268 <listitem><para>
 269         prcnt: the number of bytes of parameters begin sent.
 270 </para></listitem>
 271 <listitem><para>
 272         drcnt:   the number of bytes of data begin sent.
 273 </para></listitem>
 274 <listitem><para>
 275         mprcnt:  the maximum number of bytes of parameters which should be returned
 276 </para></listitem>
 277 <listitem><para>
 278         mdrcnt:  the maximum number of bytes of data which should be returned
 279 </para></listitem>
 280 <listitem><para>
 281         param:   a pointer to the parameters to be sent.
 282 </para></listitem>
 283 <listitem><para>
 284         data:    a pointer to the data to be sent.
 285 </para></listitem>
 286 <listitem><para>
 287         rparam:  a pointer to a pointer which will be set to point to the returned
 288         paramters.  The caller of call_api() must deallocate this memory.
 289 </para></listitem>
 290 <listitem><para>
 291         rdata:   a pointer to a pointer which will be set to point to the returned
 292         data.  The caller of call_api() must deallocate this memory.
 293 </para></listitem>
 294 </orderedlist>
 295
 296 <para>
 297 These are the parameters which you ought to send, in the order of their
 298 appearance in the parameter block:
 299 </para>
 300
 301 <orderedlist>
 302
 303 <listitem><para>
 304 An unsigned 16 bit integer API number.  You should set this value with
 305 SSVAL().  I do not know where these numbers are described.
 306 </para></listitem>
 307
 308 <listitem><para>
 309 An ASCIIZ string describing the parameters to the API function as defined
 310 in the LAN Manager documentation.  The first parameter, which is the server
 311 name, is ommited.  This string is based uppon the API function as described
 312 in the manual, not the data which is actually passed.
 313 </para></listitem>
 314
 315 <listitem><para>
 316 An ASCIIZ string describing the data structure which ought to be returned.
 317 </para></listitem>
 318
 319 <listitem><para>
 320 Any parameters which appear in the function call, as defined in the LAN
 321 Manager API documentation, after the "Server" and up to and including the
 322 "uLevel" parameters.
 323 </para></listitem>
 324
 325 <listitem><para>
 326 An unsigned 16 bit integer which gives the size in bytes of the buffer we
 327 will use to receive the returned array of data structures.  Presumably this
 328 should be the same as mdrcnt.  This value should be set with SSVAL().
 329 </para></listitem>
 330
 331 <listitem><para>
 332 An ASCIIZ string describing substructures which should be returned.  If no
 333 substructures apply, this string is of zero length.
 334 </para></listitem>
 335
 336 </orderedlist>
 337
 338 <para>
 339 The code in client.c always calls call_api() with no data.  It is unclear
 340 when a non-zero length data buffer would be sent.
 341 </para>
 342
 343 </sect2>
 344
 345 <sect2>
 346 <title>Return value</title>
 347
 348 <para>
 349 The returned parameters (pointed to by rparam), in their order of appearance
 350 are:</para>
 351
 352 <orderedlist>
 353
 354 <listitem><para>
 355 An unsigned 16 bit integer which contains the API function's return code.
 356 This value should be read with SVAL().
 357 </para></listitem>
 358
 359 <listitem><para>
 360 An adjustment which tells the amount by which pointers in the returned
 361 data should be adjusted.  This value should be read with SVAL().  Basically,
 362 the address of the start of the returned data buffer should have the returned
 363 pointer value added to it and then have this value subtracted from it in
 364 order to obtain the currect offset into the returned data buffer.
 365 </para></listitem>
 366
 367 <listitem><para>
 368 A count of the number of elements in the array of structures returned.
 369 It is also possible that this may sometimes be the number of bytes returned.
 370 </para></listitem>
 371 </orderedlist>
 372
 373 <para>
 374 When call_api() returns, rparam points to the returned parameters.  The
 375 first if these is the result code.  It will be zero if the API call
 376 suceeded.  This value by be read with "SVAL(rparam,0)".
 377 </para>
 378
 379 <para>
 380 The second parameter may be read as "SVAL(rparam,2)".  It is a 16 bit offset
 381 which indicates what the base address of the returned data buffer was when
 382 it was built on the server.  It should be used to correct pointer before
 383 use.
 384 </para>
 385
 386 <para>
 387 The returned data buffer contains the array of returned data structures.
 388 Note that all pointers must be adjusted before use.  The function
 389 fix_char_ptr() in client.c can be used for this purpose.
 390 </para>
 391
 392 <para>
 393 The third parameter (which may be read as "SVAL(rparam,4)") has something to
 394 do with indicating the amount of data returned or possibly the amount of
 395 data which can be returned if enough buffer space is allowed.
 396 </para>
 397
 398 </sect2>
 399 </sect1>
 400
 401 <sect1>
 402 <title>Code character table</title>
 403 <para>
 404 Certain data structures are described by means of ASCIIz strings containing
 405 code characters.  These are the code characters:
 406 </para>
 407
 408 <orderedlist>
 409 <listitem><para>
 410 W       a type byte little-endian unsigned integer
 411 </para></listitem>
 412 <listitem><para>
 413 N       a count of substructures which follow
 414 </para></listitem>
 415 <listitem><para>
 416 D       a four byte little-endian unsigned integer
 417 </para></listitem>
 418 <listitem><para>
 419 B       a byte (with optional count expressed as trailing ASCII digits)
 420 </para></listitem>
 421 <listitem><para>
 422 z       a four byte offset to a NULL terminated string
 423 </para></listitem>
 424 <listitem><para>
 425 l       a four byte offset to non-string user data
 426 </para></listitem>
 427 <listitem><para>
 428 b       an offset to data (with count expressed as trailing ASCII digits)
 429 </para></listitem>
 430 <listitem><para>
 431 r       pointer to returned data buffer???
 432 </para></listitem>
 433 <listitem><para>
 434 L       length in bytes of returned data buffer???
 435 </para></listitem>
 436 <listitem><para>
 437 h       number of bytes of information available???
 438 </para></listitem>
 439 </orderedlist>
 440
 441 </sect1>
 442 </chapter>