diff options
Diffstat (limited to 'contrib/sendmail/libsm/index.html')
| -rw-r--r-- | contrib/sendmail/libsm/index.html | 174 |
1 files changed, 0 insertions, 174 deletions
diff --git a/contrib/sendmail/libsm/index.html b/contrib/sendmail/libsm/index.html deleted file mode 100644 index f2eec16e6c07..000000000000 --- a/contrib/sendmail/libsm/index.html +++ /dev/null @@ -1,174 +0,0 @@ -<html> -<head> - <title>libsm Overview</title> -</head> -<body> - -<center> - <h1> libsm Overview </h1> - <br> $Id: index.html,v 1.14 2001/02/13 21:21:25 gshapiro Exp $ -</center> - -<h2> Introduction </h2> - -Libsm is a library of generally useful C abstractions. -Libsm stands alone; it depends on no other sendmail libraries, -and the only sendmail header files it depends on are its own, -which reside in <tt>../include/sm</tt>. - -<h2> Contents </h2> - -Here is the current set of packages: -<blockquote> - <a href="gen.html"> gen: general definitions </a><br> - <a href="debug.html"> debug: debugging and tracing </a><br> - <a href="assert.html"> assert: assertion handling and aborts </a><br> - <a href="heap.html"> heap: memory allocation </a><br> - <a href="exc.html"> exc: exception handling </a><br> - <a href="rpool.html"> rpool: resource pools </a><br> - <a href="cdefs.html"> cdefs: C language portability macros </a><br> - <a href="io.html"> io: buffered i/o </a><br> -</blockquote> - -<h2> Naming Conventions </h2> - - Some of the symbols defined by libsm - come from widely used defacto or dejure standards. - Examples include <tt>size_t</tt> (from the C 89 standard), - <tt>bool</tt> (from the C 99 standard), - <tt>strerror</tt> (from Posix), - and <tt>__P</tt> (from BSD and Linux). - In these cases, we use the standard name rather than - inventing a new name. - We import the name from the appropriate header file when possible, - or define it ourselves when necessary. - When you are using one of these abstractions, you must include - the appropriate libsm header file. - For example, when you are using <tt>strerror</tt>, you must - include <tt><sm/string.h></tt> instead of <tt><string.h></tt>. - - <p> - When we aren't implementing a standard interface, - we use a naming convention that attempts to maximize portability - across platforms, and minimize conflicts with other libraries. - Except for a few seemingly benign exceptions, - all names begin with <tt>SM_</tt>, <tt>Sm</tt> or <tt>sm_</tt>. - - <p> - The ISO C, Posix and Unix standards forbid applications - from using names beginning with <tt>__</tt> or <tt>_[A-Z]</tt>, - and place restrictions on what sorts of names can begin - with <tt>_[a-z]</tt>. Such names are reserved for the compiler and - the standard libraries. - For this reason, we avoid defining any names that begin - with <tt>_</tt>. - For example, all libsm header file idempotency macros have the form - <tt>SM_FOO_H</tt> (no leading <tt>_</tt>). - - <p> - Type names begin with <tt>SM_</tt> and end with <tt>_T</tt>. - Note that the Posix standard reserves all identifiers ending - with <tt>_t</tt>. - - <p> - All functions that are capable of raising an exception - have names ending in <tt>_x</tt>, and developers are - encouraged to use this convention when writing new code. - This naming convention may seem unnecessary at first, - but it becomes extremely useful during maintenance, - when you are attempting to reason about the correctness - of a block of code, - and when you are trying to track down exception-related bugs - in existing code. - -<h2> Coding Conventions </h2> - -The official style for function prototypes in libsm header files is - -<blockquote><pre> -extern int -foo __P(( - int _firstarg, - int _secondarg)); -</pre></blockquote> - -The <tt>extern</tt> is useless, but required for stylistic reasons. -The parameter names are optional; if present they are lowercase -and begin with _ to avoid namespace conflicts. -Each parameter is written on its own line to avoid very long lines. - -<p> -For each structure <tt>struct sm_foo</tt> defined by libsm, -there is a typedef: - -<blockquote><pre> -typedef struct sm_foo SM_FOO_T; -</pre></blockquote> - -and there is a global variable which is defined as follows: - -<blockquote><pre> -const char SmFooMagic[] = "sm_foo"; -</pre></blockquote> - -The first member of each structure defined by libsm is - -<blockquote><pre> -const char *sm_magic; -</pre></blockquote> - -For all instances of <tt>struct sm_foo</tt>, -<tt>sm_magic</tt> contains <tt>SmFooMagic</tt>, -which points to a unique character string naming the type. -It is used for debugging and run time type checking. - -<p> -Each function with a parameter declared <tt>SM_FOO_T *foo</tt> -contains the following assertion: - -<blockquote><pre> -SM_REQUIRE_ISA(foo, SmFooMagic); -</pre></blockquote> - -which is equivalent to - -<blockquote><pre> -SM_REQUIRE(foo != NULL && foo->sm_magic == SmFooMagic); -</pre></blockquote> - -When an object of type <tt>SM_FOO_T</tt> is deallocated, -the member <tt>sm_magic</tt> is set to <tt>NULL</tt>. -That will cause the above assertion to fail if a dangling pointer is used. - -<h2> Additional Design Goals </h2> - -Here are some of my design goals: -<ul> - <p> -<li>The sm library is self contained; it does not depend on any other - sendmail libraries or header files. - <p> -<li>The sm library must be compatible with shared libraries, - even on platforms with weird implementation restrictions. - I assume that a shared library can export global variables; - the debug package relies on this assumption. - I do not assume that if an application redefines a function defined - in a shared library, the shared library will use the version of the - function defined in the application in preference to the version - that it defines. - For this reason, I provide interfaces for registering handler functions - in cases where an application might need to override standard behaviour. - <p> -<li>The sm library must be compatible with threads. - The debug package presents a small problem: I don't want - sm_debug_active to acquire and release a lock. - So I assume that - there exists an integral type <tt>SM_ATOMIC_INT_T</tt> - (see <a href="gen.html"><tt><sm/gen.h></tt></a>) - that can be accessed and updated atomically. - I assume that locking must be used to guard updates and accesses to - any other type, and I have designed the interfaces accordingly. -</ul> - -</body> -</html> |