docs/devel/internals.xml

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