From dbd241f3421731692cbeae96db9d3bd11bc4f602 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 1 May 2003 14:00:10 +0000 Subject: Merge over Alexanders' conversion to Docbook XML (This used to be commit b0e3fa7a3657a82a208fdee6cb587705db2b5ac4) --- docs/docbook/devdoc/internals.sgml | 440 ------------------------------------- 1 file changed, 440 deletions(-) delete mode 100644 docs/docbook/devdoc/internals.sgml (limited to 'docs/docbook/devdoc/internals.sgml') diff --git a/docs/docbook/devdoc/internals.sgml b/docs/docbook/devdoc/internals.sgml deleted file mode 100644 index 982cfd2e10..0000000000 --- a/docs/docbook/devdoc/internals.sgml +++ /dev/null @@ -1,440 +0,0 @@ - - - - DavidChappell - -
David.Chappell@mail.trincoll.edu
- - - 8 May 1996 - - -Samba Internals - - -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: - - - - - must not contain NULLs except for termination - - - - 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. - - - - when you uppercase or lowercase a string it does not become - longer than the original string - - - - 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 - paramters. 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??? - - - - - -- cgit