source3/internals.doc

   1 internals.txt, 8 May 1996
   2 Written by David Chappell <David.Chappell@mail.trincoll.edu>.
   3
   4 This document describes some of the internal functions which must be
   5 understood by anyone wishing to add features to Samba.
   6
   7
   8
   9 =============================================================================
  10 This section describes character set handling in Samba, as implemented in
  11 Samba 3.0 and above
  12
  13 In the past Samba had very ad-hoc character set handling. Scattered
  14 throughout the code were numerous calls which converted particular
  15 strings to/from DOS codepages. The problem is that there was no way of
  16 telling if a particular char* is in dos codepage or unix
  17 codepage. This led to a nightmare of code that tried to cope with
  18 particular cases without handlingt the general case.
  19
  20 The new system works like this:
  21
  22 - all char* strings inside Samba are "unix" strings. These are
  23   multi-byte strings that are in the charset defined by the "unix
  24   charset" option in smb.conf.
  25
  26 - there is no single fixed character set for unix strings, but any
  27   character set that is used does need the following properties:
  28     * must not contain NULLs except for termination
  29     * must be 7-bit compatible with C strings, so that a constant
  30       string or character in C will be byte-for-byte identical to the
  31       equivalent string in the chosen character set.
  32     * when you uppercase or lowercase a string it does not become
  33       longer than the original string
  34     * must be able to correctly hold all characters that your client
  35       will throw at it
  36   For example, UTF-8 is fine, and most multi-byte asian character sets
  37   are fine, but UCS2 could not be used for unix strings as they
  38   contain nulls.
  39
  40 - when you need to put a string into a buffer that will be sent on the
  41   wire, or you need a string in a character set format that is
  42   compatible with the clients character set then you need to use a
  43   pull_ or push_ function. The pull_ functions pull a string from a
  44   wire buffer into a (multi-byte) unix string. The push_ functions
  45   push a string out to a wire buffer.
  46
  47 - the two main pull_ and push_ functions you need to understand are
  48   pull_string and push_string. These functions take a base pointer
  49   that should point at the start of the SMB packet that the string is
  50   in. The functions will check the flags field in this packet to
  51   automatically determine if the packet is marked as a unicode packet,
  52   and they will choose whether to use unicode for this string based on
  53   that flag. You may also force this decision using the STR_UNICODE or
  54   STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper
  55   functions clistr_ and srvstr_ that call the pull_/push_ functions
  56   with the appropriate first argument.
  57
  58   You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2
  59   functions if you know that a particular string is ascii or
  60   unicode. There are also a number of other convenience functions in
  61   charcnv.c that call the pull_/push_ functions with particularly
  62   common arguments, such as pull_ascii_pstring()
  63
  64 The biggest thing to remember is that internal (unix) strings in Samba
  65 may now contain multi-byte characters. This means you cannot assume
  66 that characters are always 1 byte long. Often this means that you will
  67 have to convert strings to ucs2 and back again in order to do some
  68 (seemingly) simple task. For examples of how to do this see functions
  69 like strchr_m(). I know this is very slow, and we will eventually
  70 speed it up but right now we want this stuff correct not fast.
  71
  72 Other rules:
  73
  74   - all lp_ functions now return unix strings. The magic "DOS" flag on
  75     parameters is gone.
  76   - all vfs functions take unix strings. Don't convert when passing to
  77     them
  78
  79
  80 =============================================================================
  81 This section describes the macros defined in byteorder.h.  These macros
  82 are used extensively in the Samba code.
  83
  84 -----------------------------------------------------------------------------
  85 CVAL(buf,pos)
  86
  87 returns the byte at offset pos within buffer buf as an unsigned character.
  88
  89 -----------------------------------------------------------------------------
  90 PVAL(buf,pos)
  91
  92 returns the value of CVAL(buf,pos) cast to type unsigned integer.
  93
  94 -----------------------------------------------------------------------------
  95 SCVAL(buf,pos,val)
  96
  97 sets the byte at offset pos within buffer buf to value val.
  98
  99 -----------------------------------------------------------------------------
 100 SVAL(buf,pos)
 101
 102 returns the value of the unsigned short (16 bit) little-endian integer at
 103 offset pos within buffer buf.  An integer of this type is sometimes
 104 refered to as "USHORT".
 105
 106 -----------------------------------------------------------------------------
 107 IVAL(buf,pos)
 108
 109 returns the value of the unsigned 32 bit little-endian integer at offset
 110 pos within buffer buf.
 111
 112 -----------------------------------------------------------------------------
 113 SVALS(buf,pos)
 114
 115 returns the value of the signed short (16 bit) little-endian integer at
 116 offset pos within buffer buf.
 117
 118 -----------------------------------------------------------------------------
 119 IVALS(buf,pos)
 120
 121 returns the value of the signed 32 bit little-endian integer at offset pos
 122 within buffer buf.
 123
 124 -----------------------------------------------------------------------------
 125 SSVAL(buf,pos,val)
 126
 127 sets the unsigned short (16 bit) little-endian integer at offset pos within
 128 buffer buf to value val.
 129
 130 -----------------------------------------------------------------------------
 131 SIVAL(buf,pos,val)
 132
 133 sets the unsigned 32 bit little-endian integer at offset pos within buffer
 134 buf to the value val.
 135
 136 -----------------------------------------------------------------------------
 137 SSVALS(buf,pos,val)
 138
 139 sets the short (16 bit) signed little-endian integer at offset pos within
 140 buffer buf to the value val.
 141
 142 -----------------------------------------------------------------------------
 143 SIVALS(buf,pos,val)
 144
 145 sets the signed 32 bit little-endian integer at offset pos withing buffer
 146 buf to the value val.
 147
 148 -----------------------------------------------------------------------------
 149 RSVAL(buf,pos)
 150
 151 returns the value of the unsigned short (16 bit) big-endian integer at
 152 offset pos within buffer buf.
 153
 154 -----------------------------------------------------------------------------
 155 RIVAL(buf,pos)
 156
 157 returns the value of the unsigned 32 bit big-endian integer at offset
 158 pos within buffer buf.
 159
 160 -----------------------------------------------------------------------------
 161 RSSVAL(buf,pos,val)
 162
 163 sets the value of the unsigned short (16 bit) big-endian integer at
 164 offset pos within buffer buf to value val.
 165 refered to as "USHORT".
 166
 167 -----------------------------------------------------------------------------
 168 RSIVAL(buf,pos,val)
 169
 170 sets the value of the unsigned 32 bit big-endian integer at offset
 171 pos within buffer buf to value val.
 172
 173
 174
 175
 176
 177 =============================================================================
 178 This section describes the functions need to make a LAN Manager RPC call.
 179 This information had been obtained by examining the Samba code and the LAN
 180 Manager 2.0 API documentation.  It should not be considered entirely
 181 reliable.
 182
 183 -----------------------------------------------------------------------------
 184 call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt,
 185         char *param, char *data, char **rparam, char **rdata);
 186
 187 This function is defined in client.c.  It uses an SMB transaction to call a
 188 remote api.
 189
 190 The parameters are as follows:
 191
 192 prcnt:   the number of bytes of parameters begin sent.
 193 drcnt:   the number of bytes of data begin sent.
 194 mprcnt:  the maximum number of bytes of parameters which should be returned
 195 mdrcnt:  the maximum number of bytes of data which should be returned
 196 param:   a pointer to the parameters to be sent.
 197 data:    a pointer to the data to be sent.
 198 rparam:  a pointer to a pointer which will be set to point to the returned
 199          paramters.  The caller of call_api() must deallocate this memory.
 200 rdata:   a pointer to a pointer which will be set to point to the returned
 201          data.  The caller of call_api() must deallocate this memory.
 202
 203 -----------------------------------------------------------------------------
 204 These are the parameters which you ought to send, in the order of their
 205 appearance in the parameter block:
 206
 207 * An unsigned 16 bit integer API number.  You should set this value with
 208 SSVAL().  I do not know where these numbers are described.
 209
 210 * An ASCIIZ string describing the parameters to the API function as defined
 211 in the LAN Manager documentation.  The first parameter, which is the server
 212 name, is ommited.  This string is based uppon the API function as described
 213 in the manual, not the data which is actually passed.
 214
 215 * An ASCIIZ string describing the data structure which ought to be returned.
 216
 217 * Any parameters which appear in the function call, as defined in the LAN
 218 Manager API documentation, after the "Server" and up to and including the
 219 "uLevel" parameters.
 220
 221 * An unsigned 16 bit integer which gives the size in bytes of the buffer we
 222 will use to receive the returned array of data structures.  Presumably this
 223 should be the same as mdrcnt.  This value should be set with SSVAL().
 224
 225 * An ASCIIZ string describing substructures which should be returned.  If no
 226 substructures apply, this string is of zero length.
 227
 228 -----------------------------------------------------------------------------
 229 The code in client.c always calls call_api() with no data.  It is unclear
 230 when a non-zero length data buffer would be sent.
 231
 232 -----------------------------------------------------------------------------
 233 The returned parameters (pointed to by rparam), in their order of appearance
 234 are:
 235
 236 * An unsigned 16 bit integer which contains the API function's return code.
 237 This value should be read with SVAL().
 238
 239 * An adjustment which tells the amount by which pointers in the returned
 240 data should be adjusted.  This value should be read with SVAL().  Basically,
 241 the address of the start of the returned data buffer should have the returned
 242 pointer value added to it and then have this value subtracted from it in
 243 order to obtain the currect offset into the returned data buffer.
 244
 245 * A count of the number of elements in the array of structures returned.
 246 It is also possible that this may sometimes be the number of bytes returned.
 247
 248 -----------------------------------------------------------------------------
 249 When call_api() returns, rparam points to the returned parameters.  The
 250 first if these is the result code.  It will be zero if the API call
 251 suceeded.  This value by be read with "SVAL(rparam,0)".
 252
 253 The second parameter may be read as "SVAL(rparam,2)".  It is a 16 bit offset
 254 which indicates what the base address of the returned data buffer was when
 255 it was built on the server.  It should be used to correct pointer before
 256 use.
 257
 258 The returned data buffer contains the array of returned data structures.
 259 Note that all pointers must be adjusted before use.  The function
 260 fix_char_ptr() in client.c can be used for this purpose.
 261
 262 The third parameter (which may be read as "SVAL(rparam,4)") has something to
 263 do with indicating the amount of data returned or possibly the amount of
 264 data which can be returned if enough buffer space is allowed.
 265
 266 -----------------------------------------------------------------------------
 267 Certain data structures are described by means of ASCIIz strings containing
 268 code characters.  These are the code characters:
 269
 270 W       a type byte little-endian unsigned integer
 271 N       a count of substructures which follow
 272 D       a four byte little-endian unsigned integer
 273 B       a byte (with optional count expressed as trailing ASCII digits)
 274 z       a four byte offset to a NULL terminated string
 275 l       a four byte offset to non-string user data
 276 b       an offset to data (with count expressed as trailing ASCII digits)
 277 r       pointer to returned data buffer???
 278 L       length in bytes of returned data buffer???
 279 h       number of bytes of information available???
 280
 281 ----------------------------------------------------------------------------