Chapter 5. Samba Internals

Chapter 5. Samba Internals
Prev	Part II. Samba Basics	Next

David Chappell

<David.Chappell@mail.trincoll.edu>

8 May 1996

Character Handling

-This section describes character set handling in Samba, as implemented in -Samba 3.0 and above -

-In the past Samba had very ad-hoc character set handling. Scattered -throughout the code were numerous calls which converted particular -strings to/from DOS codepages. The problem is that there was no way of -telling if a particular char* is in dos codepage or unix -codepage. This led to a nightmare of code that tried to cope with -particular cases without handlingt the general case. -

The new functions

-The new system works like this: -

- all char* strings inside Samba are "unix" strings. These are - multi-byte strings that are in the charset defined by the "unix - charset" option in smb.conf. -
- there is no single fixed character set for unix strings, but any - character set that is used does need the following properties: -
1. - must not contain NULLs except for termination -
2. - must be 7-bit compatible with C strings, so that a constant - string or character in C will be byte-for-byte identical to the - equivalent string in the chosen character set. -
3. - when you uppercase or lowercase a string it does not become - longer than the original string -
4. - must be able to correctly hold all characters that your client - will throw at it -
- For example, UTF-8 is fine, and most multi-byte asian character sets - are fine, but UCS2 could not be used for unix strings as they - contain nulls. -
- when you need to put a string into a buffer that will be sent on the - wire, or you need a string in a character set format that is - compatible with the clients character set then you need to use a - pull_ or push_ function. The pull_ functions pull a string from a - wire buffer into a (multi-byte) unix string. The push_ functions - push a string out to a wire buffer. -
- the two main pull_ and push_ functions you need to understand are - pull_string and push_string. These functions take a base pointer - that should point at the start of the SMB packet that the string is - in. The functions will check the flags field in this packet to - automatically determine if the packet is marked as a unicode packet, - and they will choose whether to use unicode for this string based on - that flag. You may also force this decision using the STR_UNICODE or - STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper - functions clistr_ and srvstr_ that call the pull_/push_ functions - with the appropriate first argument. -
- You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2 - functions if you know that a particular string is ascii or - unicode. There are also a number of other convenience functions in - charcnv.c that call the pull_/push_ functions with particularly - common arguments, such as pull_ascii_pstring() -
- The biggest thing to remember is that internal (unix) strings in Samba - may now contain multi-byte characters. This means you cannot assume - that characters are always 1 byte long. Often this means that you will - have to convert strings to ucs2 and back again in order to do some - (seemingly) simple task. For examples of how to do this see functions - like strchr_m(). I know this is very slow, and we will eventually - speed it up but right now we want this stuff correct not fast. -
- all lp_ functions now return unix strings. The magic "DOS" flag on - parameters is gone. -
- all vfs functions take unix strings. Don't convert when passing to them -

Macros in byteorder.h

-This section describes the macros defined in byteorder.h. These macros -are used extensively in the Samba code. -

CVAL(buf,pos)

-returns the byte at offset pos within buffer buf as an unsigned character. -

PVAL(buf,pos)

returns the value of CVAL(buf,pos) cast to type unsigned integer.

SCVAL(buf,pos,val)

sets the byte at offset pos within buffer buf to value val.

SVAL(buf,pos)

- returns the value of the unsigned short (16 bit) little-endian integer at - offset pos within buffer buf. An integer of this type is sometimes - refered to as "USHORT". -

IVAL(buf,pos)

returns the value of the unsigned 32 bit little-endian integer at offset -pos within buffer buf.

SVALS(buf,pos)

returns the value of the signed short (16 bit) little-endian integer at -offset pos within buffer buf.

IVALS(buf,pos)

returns the value of the signed 32 bit little-endian integer at offset pos -within buffer buf.

SSVAL(buf,pos,val)

sets the unsigned short (16 bit) little-endian integer at offset pos within -buffer buf to value val.

SIVAL(buf,pos,val)

sets the unsigned 32 bit little-endian integer at offset pos within buffer -buf to the value val.

SSVALS(buf,pos,val)

sets the short (16 bit) signed little-endian integer at offset pos within -buffer buf to the value val.

SIVALS(buf,pos,val)

sets the signed 32 bit little-endian integer at offset pos withing buffer -buf to the value val.

RSVAL(buf,pos)

returns the value of the unsigned short (16 bit) big-endian integer at -offset pos within buffer buf.

RIVAL(buf,pos)

returns the value of the unsigned 32 bit big-endian integer at offset -pos within buffer buf.

RSSVAL(buf,pos,val)

sets the value of the unsigned short (16 bit) big-endian integer at -offset pos within buffer buf to value val. -refered to as "USHORT".

RSIVAL(buf,pos,val)

sets the value of the unsigned 32 bit big-endian integer at offset -pos within buffer buf to value val.

LAN Manager Samba API

-This section describes the functions need to make a LAN Manager RPC call. -This information had been obtained by examining the Samba code and the LAN -Manager 2.0 API documentation. It should not be considered entirely -reliable. -

-call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, 
-	char *param, char *data, char **rparam, char **rdata);
-

-This function is defined in client.c. It uses an SMB transaction to call a -remote api. -

Parameters

The parameters are as follows:

- prcnt: the number of bytes of parameters begin sent. -
- drcnt: the number of bytes of data begin sent. -
- mprcnt: the maximum number of bytes of parameters which should be returned -
- mdrcnt: the maximum number of bytes of data which should be returned -
- param: a pointer to the parameters to be sent. -
- data: a pointer to the data to be sent. -
- rparam: a pointer to a pointer which will be set to point to the returned - parameters. The caller of call_api() must deallocate this memory. -
- rdata: a pointer to a pointer which will be set to point to the returned - data. The caller of call_api() must deallocate this memory. -

-These are the parameters which you ought to send, in the order of their -appearance in the parameter block: -

-An unsigned 16 bit integer API number. You should set this value with -SSVAL(). I do not know where these numbers are described. -
-An ASCIIZ string describing the parameters to the API function as defined -in the LAN Manager documentation. The first parameter, which is the server -name, is ommited. This string is based uppon the API function as described -in the manual, not the data which is actually passed. -
-An ASCIIZ string describing the data structure which ought to be returned. -
-Any parameters which appear in the function call, as defined in the LAN -Manager API documentation, after the "Server" and up to and including the -"uLevel" parameters. -
-An unsigned 16 bit integer which gives the size in bytes of the buffer we -will use to receive the returned array of data structures. Presumably this -should be the same as mdrcnt. This value should be set with SSVAL(). -
-An ASCIIZ string describing substructures which should be returned. If no -substructures apply, this string is of zero length. -

-The code in client.c always calls call_api() with no data. It is unclear -when a non-zero length data buffer would be sent. -

Return value

-The returned parameters (pointed to by rparam), in their order of appearance -are:

-An unsigned 16 bit integer which contains the API function's return code. -This value should be read with SVAL(). -
-An adjustment which tells the amount by which pointers in the returned -data should be adjusted. This value should be read with SVAL(). Basically, -the address of the start of the returned data buffer should have the returned -pointer value added to it and then have this value subtracted from it in -order to obtain the currect offset into the returned data buffer. -
-A count of the number of elements in the array of structures returned. -It is also possible that this may sometimes be the number of bytes returned. -

-When call_api() returns, rparam points to the returned parameters. The -first if these is the result code. It will be zero if the API call -suceeded. This value by be read with "SVAL(rparam,0)". -

-The second parameter may be read as "SVAL(rparam,2)". It is a 16 bit offset -which indicates what the base address of the returned data buffer was when -it was built on the server. It should be used to correct pointer before -use. -

-The returned data buffer contains the array of returned data structures. -Note that all pointers must be adjusted before use. The function -fix_char_ptr() in client.c can be used for this purpose. -

-The third parameter (which may be read as "SVAL(rparam,4)") has something to -do with indicating the amount of data returned or possibly the amount of -data which can be returned if enough buffer space is allowed. -

Code character table

-Certain data structures are described by means of ASCIIz strings containing -code characters. These are the code characters: -

-W a type byte little-endian unsigned integer -
-N a count of substructures which follow -
-D a four byte little-endian unsigned integer -
-B a byte (with optional count expressed as trailing ASCII digits) -
-z a four byte offset to a NULL terminated string -
-l a four byte offset to non-string user data -
-b an offset to data (with count expressed as trailing ASCII digits) -
-r pointer to returned data buffer??? -
-L length in bytes of returned data buffer??? -
-h number of bytes of information available??? -

Prev	Up	Next
Chapter 4. The samba DEBUG system	Home	Chapter 6. Coding Suggestions