diff options
| -rw-r--r-- | source3/CodingSuggestions | 160 | ||||
| -rw-r--r-- | source3/architecture.doc | 134 | ||||
| -rw-r--r-- | source3/internals.doc | 281 | ||||
| -rw-r--r-- | source3/parsing.doc | 363 |
4 files changed, 0 insertions, 938 deletions
diff --git a/source3/CodingSuggestions b/source3/CodingSuggestions deleted file mode 100644 index 5e99bc54ca..0000000000 --- a/source3/CodingSuggestions +++ /dev/null @@ -1,160 +0,0 @@ -/** - -@page CodingSuggestions Coding suggestions - -So you want to add code to Samba ... - -One of the daunting tasks facing a programmer attempting to write code for -Samba is understanding the various coding conventions used by those most -active in the project. These conventions were mostly unwritten and helped -improve either the portability, stability or consistency of the code. This -document will attempt to document a few of the more important coding -practices used at this time on the Samba project. The coding practices are -expected to change slightly over time, and even to grow as more is learned -about obscure portability considerations. Two existing documents -samba/source/internals.doc and samba/source/architecture.doc provide -additional information. - -The loosely related question of coding style is very personal and this -document does not attempt to address that subject, except to say that I -have observed that eight character tabs seem to be preferred in Samba -source. If you are interested in the topic of coding style, two oft-quoted -documents are: - - http://lxr.linux.no/source/Documentation/CodingStyle - http://www.fsf.org/prep/standards_toc.html - -but note that coding style in Samba varies due to the many different -programmers who have contributed. - -The indent utility can be used to format C files in the general -samba coding style. The arguments you should give to indent are: --bad -bap -br -ce -cdw -nbc -brs -bbb -nbc -npsl -ut -i8 - -Following are some considerations you should use when adding new code to -Samba. First and foremost remember that: - -Portability is a primary consideration in adding function, as is network -compatability with de facto, existing, real world CIFS/SMB implementations. -There are lots of platforms that Samba builds on so use caution when adding -a call to a library function that is not invoked in existing Samba code. -Also note that there are many quite different SMB/CIFS clients that Samba -tries to support, not all of which follow the SNIA CIFS Technical Reference -(or the earlier Microsoft reference documents or the X/Open book on the SMB -Standard) perfectly. - -Here are some other suggestions: - -1) use d_printf instead of printf for display text - reason: enable auto-substitution of translated language text - -2) use SAFE_FREE instead of free - reason: reduce traps due to null pointers - -3) don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros - reason: not POSIX - -4) don't use strcpy and strlen (use safe_* equivalents) - reason: to avoid traps due to buffer overruns - -5) don't use getopt_long, use popt functions instead - reason: portability - -6) explicitly add const qualifiers on parm passing in functions where parm - is input only (somewhat controversial but const can be #defined away) - -7) when passing a va_list as an arg, or assigning one to another - please use the VA_COPY() macro - reason: on some platforms, va_list is a struct that must be - initialized in each function...can SEGV if you don't. - -8) discourage use of threads - reason: portability (also see architecture.doc) - -9) don't explicitly include new header files in C files - new h files - should be included by adding them once to includes.h - reason: consistency - -10) don't explicitly extern functions (they are autogenerated by - "make proto" into proto.h) - reason: consistency - -11) use endian safe macros when unpacking SMBs (see byteorder.h and - internals.doc) - reason: not everyone uses Intel - -12) Note Unicode implications of charset handling (see internals.doc). See - pull_* and push_* and convert_string functions. - reason: Internationalization - -13) Don't assume English only - reason: See above - -14) Try to avoid using in/out parameters (functions that return data which - overwrites input parameters) - reason: Can cause stability problems - -15) Ensure copyright notices are correct, don't append Tridge's name to code - that he didn't write. If you did not write the code, make sure that it - can coexist with the rest of the Samba GPLed code. - -16) Consider usage of DATA_BLOBs for length specified byte-data. - reason: stability - -17) Take advantage of tdbs for database like function - reason: consistency - -18) Don't access the SAM_ACCOUNT structure directly, they should be accessed - via pdb_get...() and pdb_set...() functions. - reason: stability, consistency - -19) Don't check a password directly against the passdb, always use the - check_password() interface. - reason: long term pluggability - -20) Try to use asprintf rather than pstrings and fstrings where possible - -21) Use normal C comments / * instead of C++ comments // like - this. Although the C++ comment format is part of the C99 - standard, some older vendor C compilers do not accept it. - -22) Try to write documentation for API functions and structures - explaining the point of the code, the way it should be used, and - any special conditions or results. Mark these with a double-star - comment start / ** so that they can be picked up by Doxygen, as in - this file. - -23) Keep the scope narrow. This means making functions/variables - static whenever possible. We don't want our namespace - polluted. Each module should have a minimal number of externally - visible functions or variables. - -24) Use function pointers to keep knowledge about particular pieces of - code isolated in one place. We don't want a particular piece of - functionality to be spread out across lots of places - that makes - for fragile, hand to maintain code. Instead, design an interface - and use tables containing function pointers to implement specific - functionality. This is particularly important for command - interpreters. - -25) Think carefully about what it will be like for someone else to add - to and maintain your code. If it would be hard for someone else to - maintain then do it another way. - -26) Always keep the declaration of a function on one line. The autoprototyper - doesn't catch declarations spread over multiple lines. - Use: -static char foo(int bar) - and not: -static char -foo(int bar) - -The suggestions above are simply that, suggestions, but the information may -help in reducing the routine rework done on new code. The preceeding list -is expected to change routinely as new support routines and macros are -added. - -Written by Steve French, with contributions from Simo Sorce, Andrew -Bartlett, Tim Potter, Martin Pool and Jelmer Vernooij. - -**/ diff --git a/source3/architecture.doc b/source3/architecture.doc deleted file mode 100644 index eb29792bea..0000000000 --- a/source3/architecture.doc +++ /dev/null @@ -1,134 +0,0 @@ -Samba Architecture ------------------- - -First preliminary version Dan Shearer Nov 97 -Quickly scrabbled together from odd bits of mail and memory. Please update. - -This document gives a general overview of how Samba works -internally. The Samba Team has tried to come up with a model which is -the best possible compromise between elegance, portability, security -and the constraints imposed by the very messy SMB and CIFS -protocol. - -It also tries to answer some of the frequently asked questions such as: - - * Is Samba secure when running on Unix? The xyz platform? - What about the root priveliges issue? - - * Pros and cons of multithreading in various parts of Samba - - * Why not have a separate process for name resolution, WINS, - and browsing? - - -Multithreading and Samba ------------------------- - -People sometimes tout threads as a uniformly good thing. They are very -nice in their place but are quite inappropriate for smbd. nmbd is -another matter, and multi-threading it would be very nice. - -The short version is that smbd is not multithreaded, and alternative -servers that take this approach under Unix (such as Syntax, at the -time of writing) suffer tremendous performance penalties and are less -robust. nmbd is not threaded either, but this is because it is not -possible to do it while keeping code consistent and portable across 35 -or more platforms. (This drawback also applies to threading smbd.) - -The longer versions is that there are very good reasons for not making -smbd multi-threaded. Multi-threading would actually make Samba much -slower, less scalable, less portable and much less robust. The fact -that we use a separate process for each connection is one of Samba's -biggest advantages. - -Threading smbd --------------- - -A few problems that would arise from a threaded smbd are: - -0) It's not only to create threads instead of processes, but you - must care about all variables if they have to be thread specific - (currently they would be global). - -1) if one thread dies (eg. a seg fault) then all threads die. We can -immediately throw robustness out the window. - -2) many of the system calls we make are blocking. Non-blocking -equivalents of many calls are either not available or are awkward (and -slow) to use. So while we block in one thread all clients are -waiting. Imagine if one share is a slow NFS filesystem and the others -are fast, we will end up slowing all clients to the speed of NFS. - -3) you can't run as a different uid in different threads. This means -we would have to switch uid/gid on _every_ SMB packet. It would be -horrendously slow. - -4) the per process file descriptor limit would mean that we could only -support a limited number of clients. - -5) we couldn't use the system locking calls as the locking context of -fcntl() is a process, not a thread. - -Threading nmbd --------------- - -This would be ideal, but gets sunk by portability requirements. - -Andrew tried to write a test threads library for nmbd that used only -ansi-C constructs (using setjmp and longjmp). Unfortunately some OSes -defeat this by restricting longjmp to calling addresses that are -shallower than the current address on the stack (apparently AIX does -this). This makes a truly portable threads library impossible. So to -support all our current platforms we would have to code nmbd both with -and without threads, and as the real aim of threads is to make the -code clearer we would not have gained anything. (it is a myth that -threads make things faster. threading is like recursion, it can make -things clear but the same thing can always be done faster by some -other method) - -Chris tried to spec out a general design that would abstract threading -vs separate processes (vs other methods?) and make them accessible -through some general API. This doesn't work because of the data -sharing requirements of the protocol (packets in the future depending -on packets now, etc.) At least, the code would work but would be very -clumsy, and besides the fork() type model would never work on Unix. (Is there an OS that it would work on, for nmbd?) - -A fork() is cheap, but not nearly cheap enough to do on every UDP -packet that arrives. Having a pool of processes is possible but is -nasty to program cleanly due to the enormous amount of shared data (in -complex structures) between the processes. We can't rely on each -platform having a shared memory system. - -nbmd Design ------------ - -Originally Andrew used recursion to simulate a multi-threaded -environment, which use the stack enormously and made for really -confusing debugging sessions. Luke Leighton rewrote it to use a -queuing system that keeps state information on each packet. The -first version used a single structure which was used by all the -pending states. As the initialisation of this structure was -done by adding arguments, as the functionality developed, it got -pretty messy. So, it was replaced with a higher-order function -and a pointer to a user-defined memory block. This suddenly -made things much simpler: large numbers of functions could be -made static, and modularised. This is the same principle as used -in NT's kernel, and achieves the same effect as threads, but in -a single process. - -Then Jeremy rewrote nmbd. The packet data in nmbd isn't what's on the -wire. It's a nice format that is very amenable to processing but still -keeps the idea of a distinct packet. See "struct packet_struct" in -nameserv.h. It has all the detail but none of the on-the-wire -mess. This makes it ideal for using in disk or memory-based databases -for browsing and WINS support. - -nmbd now consists of a series of modules. It... - - -Samba Design and Security -------------------------- - -Why Isn't nmbd Multiple Daemons? --------------------------------- - diff --git a/source3/internals.doc b/source3/internals.doc deleted file mode 100644 index c8cc6dd136..0000000000 --- a/source3/internals.doc +++ /dev/null @@ -1,281 +0,0 @@ -internals.txt, 8 May 1996 -Written by David Chappell <David.Chappell@mail.trincoll.edu>. - -This document describes some of the internal functions which must be -understood by anyone wishing to add features to Samba. - - - -============================================================================= -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 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. - -Other rules: - - - 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 - - -============================================================================= -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. - - - - - -============================================================================= -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. - -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. - ------------------------------------------------------------------------------ -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. - ------------------------------------------------------------------------------ -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??? - ----------------------------------------------------------------------------- diff --git a/source3/parsing.doc b/source3/parsing.doc deleted file mode 100644 index d26a64ae4e..0000000000 --- a/source3/parsing.doc +++ /dev/null @@ -1,363 +0,0 @@ -Chris Hertel, Samba Team -November 1997 - -This is a quick overview of the lexical analysis, syntax, and semantics -of the smb.conf file. - -Lexical Analysis: - - Basically, the file is processed on a line by line basis. There are - four types of lines that are recognized by the lexical analyzer - (params.c): - - Blank lines - Lines containing only whitespace. - Comment lines - Lines beginning with either a semi-colon or a - pound sign (';' or '#'). - Section header lines - Lines beginning with an open square bracket - ('['). - Parameter lines - Lines beginning with any other character. - (The default line type.) - - The first two are handled exclusively by the lexical analyzer, which - ignores them. The latter two line types are scanned for - - - Section names - - Parameter names - - Parameter values - - These are the only tokens passed to the parameter loader - (loadparm.c). Parameter names and values are divided from one - another by an equal sign: '='. - - - Handling of Whitespace: - - Whitespace is defined as all characters recognized by the isspace() - function (see ctype(3C)) except for the newline character ('\n') - The newline is excluded because it identifies the end of the line. - - - The lexical analyzer scans past white space at the beginning of a - line. - - - Section and parameter names may contain internal white space. All - whitespace within a name is compressed to a single space character. - - - Internal whitespace within a parameter value is kept verbatim with - the exception of carriage return characters ('\r'), all of which - are removed. - - - Leading and trailing whitespace is removed from names and values. - - - Handling of Line Continuation: - - Long section header and parameter lines may be extended across - multiple lines by use of the backslash character ('\\'). Line - continuation is ignored for blank and comment lines. - - If the last (non-whitespace) character within a section header or on - a parameter line is a backslash, then the next line will be - (logically) concatonated with the current line by the lexical - analyzer. For example: - - param name = parameter value string \ - with line continuation. - - Would be read as - - param name = parameter value string with line continuation. - - Note that there are five spaces following the word 'string', - representing the one space between 'string' and '\\' in the top - line, plus the four preceeding the word 'with' in the second line. - (Yes, I'm counting the indentation.) - - Line continuation characters are ignored on blank lines and at the end - of comments. They are *only* recognized within section and parameter - lines. - - - Line Continuation Quirks: - - Note the following example: - - param name = parameter value string \ - \ - with line continuation. - - The middle line is *not* parsed as a blank line because it is first - concatonated with the top line. The result is - - param name = parameter value string with line continuation. - - The same is true for comment lines. - - param name = parameter value string \ - ; comment \ - with a comment. - - This becomes: - - param name = parameter value string ; comment with a comment. - - On a section header line, the closing bracket (']') is considered a - terminating character, and the rest of the line is ignored. The lines - - [ section name ] garbage \ - param name = value - - are read as - - [section name] - param name = value - - - -Syntax: - - The syntax of the smb.conf file is as follows: - - <file> :== { <section> } EOF - - <section> :== <section header> { <parameter line> } - - <section header> :== '[' NAME ']' - - <parameter line> :== NAME '=' VALUE NL - - - Basically, this means that - - - a file is made up of zero or more sections, and is terminated by - an EOF (we knew that). - - - A section is made up of a section header followed by zero or more - parameter lines. - - - A section header is identified by an opening bracket and - terminated by the closing bracket. The enclosed NAME identifies - the section. - - - A parameter line is divided into a NAME and a VALUE. The *first* - equal sign on the line separates the NAME from the VALUE. The - VALUE is terminated by a newline character (NL = '\n'). - - -About params.c: - - The parsing of the config file is a bit unusual if you are used to - lex, yacc, bison, etc. Both lexical analysis (scanning) and parsing - are performed by params.c. Values are loaded via callbacks to - loadparm.c. - --------------------------------------------------------------------------- - - Samba DEBUG - -Chris Hertel, Samba Team -July, 1998 - - Here's the scoop on the update to the DEBUG() system. - - First, my goals are: - * Backward compatibility (ie., I don't want to break any Samba code - that already works). - * Debug output should be timestamped and easy to read (format-wise). - * Debug output should be parsable by software. - * There should be convenient tools for composing debug messages. - - NOTE: the Debug functionality has been moved from util.c to the new - debug.c module. - -New Output Syntax - - The syntax of a debugging log file is represented as: - <debugfile> :== { <debugmsg> } - - <debugmsg> :== <debughdr> '\n' <debugtext> - - <debughdr> :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')' - - <debugtext> :== { <debugline> } - - <debugline> :== TEXT '\n' - - TEXT is a string of characters excluding the newline character. - LEVEL is the DEBUG level of the message (an integer in the range - 0..10). - TIME is a timestamp. - FILE is the name of the file from which the debug message was - generated. - FUNCTION is the function from which the debug message was generated. - LINE is the line number of the debug statement that generated the - message. - - Basically, what that all means is: - * A debugging log file is made up of debug messages. - * Each debug message is made up of a header and text. The header is - separated from the text by a newline. - * The header begins with the timestamp and debug level of the - message enclosed in brackets. The filename, function, and line - number at which the message was generated follow. The filename is - terminated by a colon, and the function name is terminated by the - parenthesis which contain the line number. Depending upon the - compiler, the function name may be missing (it is generated by the - __FUNCTION__ macro, which is not universally implemented, dangit). - * The message text is made up of zero or more lines, each terminated - by a newline. - - Here's some example output: - - [1998/08/03 12:55:25, 1] nmbd.c:(659) - Netbios nameserver version 1.9.19-prealpha started. - Copyright Andrew Tridgell 1994-1997 - [1998/08/03 12:55:25, 3] loadparm.c:(763) - Initializing global parameters - - Note that in the above example the function names are not listed on - the header line. That's because the example above was generated on an - SGI Indy, and the SGI compiler doesn't support the __FUNCTION__ macro. - -The DEBUG() Macro - - Use of the DEBUG() macro is unchanged. DEBUG() takes two parameters. - The first is the message level, the second is the body of a function - call to the Debug1() function. - - That's confusing. - - Here's an example which may help a bit. If you would write - - printf( "This is a %s message.\n", "debug" ); - - to send the output to stdout, then you would write - - DEBUG( 0, ( "This is a %s message.\n", "debug" ) ); - - to send the output to the debug file. All of the normal printf() - formatting escapes work. - - Note that in the above example the DEBUG message level is set to 0. - Messages at level 0 always print. Basically, if the message level is - less than or equal to the global value DEBUGLEVEL, then the DEBUG - statement is processed. - - The output of the above example would be something like: - - [1998/07/30 16:00:51, 0] file.c:function(128) - This is a debug message. - - Each call to DEBUG() creates a new header *unless* the output produced - by the previous call to DEBUG() did not end with a '\n'. Output to the - debug file is passed through a formatting buffer which is flushed - every time a newline is encountered. If the buffer is not empty when - DEBUG() is called, the new input is simply appended. - - ...but that's really just a Kludge. It was put in place because - DEBUG() has been used to write partial lines. Here's a simple (dumb) - example of the kind of thing I'm talking about: - - DEBUG( 0, ("The test returned " ) ); - if( test() ) - DEBUG(0, ("True") ); - else - DEBUG(0, ("False") ); - DEBUG(0, (".\n") ); - - Without the format buffer, the output (assuming test() returned true) - would look like this: - - [1998/07/30 16:00:51, 0] file.c:function(256) - The test returned - [1998/07/30 16:00:51, 0] file.c:function(258) - True - [1998/07/30 16:00:51, 0] file.c:function(261) - . - - Which isn't much use. The format buffer kludge fixes this problem. - -The DEBUGADD() Macro - - In addition to the kludgey solution to the broken line problem - described above, there is a clean solution. The DEBUGADD() macro never - generates a header. It will append new text to the current debug - message even if the format buffer is empty. The syntax of the - DEBUGADD() macro is the same as that of the DEBUG() macro. - - DEBUG( 0, ("This is the first line.\n" ) ); - DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) ); - - Produces - [1998/07/30 16:00:51, 0] file.c:function(512) - This is the first line. - This is the second line. - This is the third line. - -The DEBUGLVL() Macro - - One of the problems with the DEBUG() macro was that DEBUG() lines - tended to get a bit long. Consider this example from - nmbd_sendannounce.c: - - DEBUG(3,("send_local_master_announcement: type %x for name %s on subnet %s for workgroup %s\n", - type, global_myname, subrec->subnet_name, work->work_group)); - - One solution to this is to break it down using DEBUG() and DEBUGADD(), - as follows: - - DEBUG( 3, ( "send_local_master_announcement: " ) ); - DEBUGADD( 3, ( "type %x for name %s ", type, global_myname ) ); - DEBUGADD( 3, ( "on subnet %s ", subrec->subnet_name ) ); - DEBUGADD( 3, ( "for workgroup %s\n", work->work_group ) ); - - A similar, but arguably nicer approach is to use the DEBUGLVL() macro. - This macro returns True if the message level is less than or equal to - the global DEBUGLEVEL value, so: - - if( DEBUGLVL( 3 ) ) - { - dbgtext( "send_local_master_announcement: " ); - dbgtext( "type %x for name %s ", type, global_myname ); - dbgtext( "on subnet %s ", subrec->subnet_name ); - dbgtext( "for workgroup %s\n", work->work_group ); - } - - (The dbgtext() function is explained below.) - - There are a few advantages to this scheme: - * The test is performed only once. - * You can allocate variables off of the stack that will only be used - within the DEBUGLVL() block. - * Processing that is only relevant to debug output can be contained - within the DEBUGLVL() block. - -New Functions - - dbgtext() - This function prints debug message text to the debug file (and - possibly to syslog) via the format buffer. The function uses a - variable argument list just like printf() or Debug1(). The - input is printed into a buffer using the vslprintf() function, - and then passed to format_debug_text(). - - If you use DEBUGLVL() you will probably print the body of the - message using dbgtext(). - - dbghdr() - This is the function that writes a debug message header. - Headers are not processed via the format buffer. Also note that - if the format buffer is not empty, a call to dbghdr() will not - produce any output. See the comments in dbghdr() for more info. - - It is not likely that this function will be called directly. It - is used by DEBUG() and DEBUGADD(). - - format_debug_text() - This is a static function in debug.c. It stores the output text - for the body of the message in a buffer until it encounters a - newline. When the newline character is found, the buffer is - written to the debug file via the Debug1() function, and the - buffer is reset. This allows us to add the indentation at the - beginning of each line of the message body, and also ensures - that the output is written a line at a time (which cleans up - syslog output). |