+++ /dev/null
-/**
-
-@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.
-
-**/
+++ /dev/null
-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?
---------------------------------
-
+++ /dev/null
-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???
-
-----------------------------------------------------------------------------
+++ /dev/null
-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).
git.samba.org / tprouty / samba.git / commitdiff